The objective of this blog is to show you the steps necessary to use an existing Micrium OS USBD example and add a different class and demo using the EFM32GG11.

Baseline Project

Since the Gecko SDK currently ships with a ‘micriumos_usbdhidmouse’ project for the SLSTK3701A_EFM32GG11 board, we can make a copy of it and rename it ‘micriumos_usbdvendor’. The convenience of making a copy of the project is to modify it according to our needs without breaking the Gecko SDK default projects. Start by locating the ‘micriumos_usbdhidmouse’ folder in your Simplicity Studio installation. The project location is at ‘C:\SiliconLabs\SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\v2.5\app\mcu_example\SLSTK3701A_EFM32GG11’

Once you found the folder, make a copy of it and rename it ‘micriumos_usbdvendor’. Please make sure to keep the new folder at the same path location of the original. Locate the ‘SLSTK3701A_micriumos_usbdhidmouse.slsproj’  file inside your New Folder  ‘micriumos_usbdvendor\SimplicityStudio’ and rename it ‘SLSTK3701A_micriumos_usbdvendor.slsproj’ 

We will be adding our new workspace, so launch Simplicity Studio and connect the SLSTK3701A_EFM32GG11 board to the PC.

Add workspace by right-clicking anywhere inside the Project Explorer box and Select Import>MCU Project

Use the Browse button to locate the ‘SLSTK3701A_micriumos_usbdvendor.slsproj’ and click Next>

File Location: `C:\SiliconLabs\SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\v2.5\app\mcu_example\SLSTK3701A_EFM32GG11\micriumos_usbdvendor\SimplicityStudio`

Since you already have your board connected, it should all be auto-detected. Leave everything by default making sure that there is an SDK selected, then click Next>

You can either change the name of the project or keep the default, then click Finish.

Configuration Files

 We will now need to modify the project configuration files to include Micrium OS USBD Vendor class as part of our build. Start by expanding the Includes section in the Project Explorer panel, then expand the configuration folder as shown in the image below. After that, double-click on the rtos_configuration.h to open it in the editor.

As soon as you try to edit the rtos_description.h, you will be presented a Warning indicating you are editing an SDK file. Click on Edit in SDK.

Add the following #define in rtos_description.h to indicate Micrium OS that you want to use VENDOR class.

#define  RTOS_MODULE_USB_DEV_VENDOR_AVAIL

Remove the following #define in rtos_decription.h

#define  RTOS_MODULE_USB_DEV_HID_AVAIL

Tell Micrium OS you want to use the USBD VENDOR demo by modifying ex_description.h. Expand the Includes section in the Project Explorer panel, then expand the project folder as shown in the image below. After that, double-click on the ex_description.h to open it in the editor.

As soon as you try to edit the ex_description.h, you will be presented a Warning indicating you are editing an SDK file. Click on Edit in SDK.

Remove the following #define in ex_description.h

#define RTOS_MODULE_USB_DEV_HID_AVAIL

Add the following #define in ex_description.h  to indicate Micrium OS you want to use VENDOR class.

#define  RTOS_MODULE_USB_DEV_VENDOR_AVAIL

Adding USBD Class and Demo

Expand the src section in the Project Explorer panel and remove the ‘ex_usbd_hid_mouse.c’ linked file.

Select Import > MCU Project by right-clicking on src section as shown on image below

Choose ‘More Import Options…’  and select File System  on the next window that pops-up as shown on the images below

Add ‘ex_usbd_vendor_loopback.c’ example as shown on image below, and click Finish.

File location: 'C:\SiliconLabs\SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\v2.5\app\micrium_os_example\usb\device\all'

Expand the usb>source>device>class section in the Project Explorer  panel and right-click on class. Select Import > MCU Project  and add the USBD VENDOR class file as shown on images below

Use the Browse button to locate the  VENDOR class files to be added as shown below.

File location:  'C:\SiliconLabs\SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\v2.5\platform\micrium_os\usb\source\device\class'

Running the Example

You can now build your application and flash it on the board. Once the application starts running, you should see LED0 on the board blinking which means all the initialization was done correctly; therefore, we can now test the USBD VENDOR demo.

Use a Micro-USB B cable to connect the PC to the EFM32GG11 board. As soon as you connect it, Windows will enumerate the device and display it in 'Universal Serial Bus Devices' as shown in the image below. 

Execute the Windows USB application provided in the attachment (Located at 'App\Host\OS\Windows\Vendor\Visual Studio 2010\exe\x86') and provide the number of transfers.

An important aspect of any IoT device is how secure the device is when it communicates with other devices, gateways or the cloud. It is common for developers to secure communications such as TCP/IP connections, Bluetooth or Zigbee. However, if a microcontroller sends sensitive information over a simple interface such as a UART to another microcontroller, it is important to realize that data should also be secured to prevent someone from snooping the UART line.

Silicon Labs offers a hardware CRYPTO module that provides an efficient acceleration of common cryptographic operations and allows these to be used efficiently with low CPU overhead. In addition to the CRYPTO module, Silicon Labs also provides a mbed TLS library to integrate with mbed TLS to allow it to take advantage of the CRYPTO module acceleration.

To use mbed TLS in a Micrium OS based application, first the developer must understand how the mbed TLS library will be used in the application. By default, mbed TLS is intended to be used in a single threaded/bare metal application or used in only a single thread of an RTOS application. For a Micrium OS application, this means if there will only be one task calling mbed TLS functions then no special modifications to the config file are necessary. If mbed TLS will be called from multiple tasks, for example a Bluetooth project that has a UART to communicate to another microcontroller, then a few modifications need to be made to the mbed TLS config header.

The following instructions will show you how to enable thread protection in mbed TLS for a Micrium OS Blink project on the Giant Gecko Series 1 (SLSTK3701A). If you have any difficulty getting the project set up, a .sls file is attached to this post for you to download. If you need further information on the SiLabs’ mbed TLS library, refer to Application Node AN0955.

Open Simplicity Studio and with your GG11 plugged in, select the board under debug adapters and then expand the Software Examples. Select the SLSTK3701A_micriumos_blink project and jump to the Simplicity IDE. 

First, mbed TLS must be added to the project as its not already included. You can either download mbed TLS from https://tls.mbed.org or you can grab a copy from your install of Simplicity Studio from: Simplicity Studio install location -> Eclipse -> developer -> sdks -> gecko_sdk_suite -> v2.4 -> util -> third_party -> mbedtls. Place those files into the workspace folder for the SLSTK3701A_micriumos_blink.

Once you have mbed TLS added to the project, you need to add the SiLabs library for mbed TLS to the workspace for SLSTK3701A_micriumos_blink. Under the Simplicity Studio install you can copy the sl_crypto folder and config folder from here: Eclipse -> developer -> sdks -> gecko_sdk_suite -> v2.4 -> util -> third_party -> mbedtls.

After adding the folders to the workspace similar to the image above, include paths need to be added to the project. Under the project properties, go to C/C++ Build -> Settings -> GNU ARM C Compiler -> Includes. 

Paths need to be added for the config directory, include directory and the sl_crypto directory. After adding those paths, remain in the project settings and go to Symbols under GNU ARM C Compiler.

At this point, mbed TLS has been added to the project, but it is only set to run in its default configuration. This means it won’t take advantage of the CRYPTO module acceleration and it won’t work from multiple threads. To fix that, add a new symbol that contains the following: MBEDTLS_CONFIG_FILE="config-sl-crypto-all-acceleration.h" then click OK. This will tell all mbed TLS files to look at the new config file, rather than the default config.h file.

Open up the config-sl-crypto-all-acceleration.h under the config directory. This is the default config file for enabling all hardware accelerations supported by SiLabs’ mbed TLS library. Add the following code to the header file to enable threading and remove a requirement for network sockets (unless you plan to use them). This code must be placed directly below the #include “mbedtls/config.h”.

/* Include the default mbed TLS config file */
#include "mbedtls/config.h"

/* Add Micrium OS support */
#define MBEDTLS_THREADING_ALT
#define MBEDTLS_THREADING_C
#define MBEDTLS_MICRIUM
#undef MBEDTLS_NET_C

#undef MBEDTLS_TIMING_C

Finally, the last piece to enable Micrium OS support in mbed TLS is to initialize threading support before starting Micrium OS. In the file ex_main.c, place the following code in main() anytime after the OSInit() call and before OSStart(). This will initialize the necessary mutexes to provide the protection.

// Enable Micrium OS support
#if defined ( MBEDTLS_THREADING_C )
    THREADING_setup();
#endif

At this point, after the OSStart() call completes and multitasking has begun, any mbed TLS call can be made safely from any task in Micrium OS.

The objective of this blog is to show you the steps necessary to use an existing Micrium OS USBD example and add CDC-ACM class and demo using the EFM32GG11.

Baseline Project

Since the Gecko SDK currently ships with a ‘micriumos_usbdhidmouse’ project for the SLSTK3701A_EFM32GG11 board, we can make a copy of it and rename it ‘micriumos_usbdcdcacm’. The convenience of making a copy of the project is to modify it according to our needs without breaking the Gecko SDK default projects.

Start by locating the ‘micriumos_usbdhidmouse’ folder in your Simplicity Studio installation. The project location is at ‘C:\SiliconLabs\SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\v2.4\app\mcu_example\SLSTK3701A_EFM32GG11’

Once you found the folder, make a copy of it and rename it ‘micriumos_usbdcdcacm’. Please make sure to keep the new folder at the same path location of the original.

Locate the ‘SLSTK3701A_micriumos_usbdhidmouse.slsproj’  file inside your New Folder  ‘micriumos_usbdcdcacm\SimplicityStudio’ and rename it ‘SLSTK3701A_micriumos_usbdcdcacm.slsproj’ 

We will be adding our new workspace, so launch Simplicity Studio and connect the SLSTK3701A_EFM32GG11 board to the PC.

Add workspace by right-clicking anywhere inside the Project Explorer box and Select Import > MCU Project

Use the Browse button to locate the ‘SLSTK3701A_micriumos_usbdcdcacm.slsproj’ and click Next>

File location: 'C:\SiliconLabs\SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\v2.4\app\mcu_example\SLSTK3701A_EFM32GG11\micriumos_usbdcdcacm\SimplicityStudio'

Since you already have your board connected, it should all be auto-detected. Leave everything by default making sure that there is an SDK selected, then click Next>

You can either change the name of the project or keep the default, then click Finish.

Configuration Files

 We will now need to modify the project configuration files in order to include Micrium OS USBD CDC-ACM class as part of our build.

Start by expanding the Includes section in the Project Explorer panel, then expand the configuration folder as shown in the image below. After that, double-click on the rtos_configuration.h to open it in the editor.

As soon as you try to edit the rtos_description.h, you will be presented a Warning indicating you are editing an SDK file. Click on Edit in SDK.

Add the following #define in rtos_description.h to indicate Micrium OS that you want to use CDC ACM class.

#define  RTOS_MODULE_USB_DEV_ACM_AVAIL
#define  RTOS_MODULE_USB_DEV_CDC_AVAIL

Remove the following #define in rtos_decription.h

#define  RTOS_MODULE_USB_DEV_HID_AVAIL

Tell Micrium OS you want to use the USBD CDC-ACM demo by modifying ex_description.h. Expand the Includes section in the Project Explorer panel, then expand the project folder as shown in the image below. After that, double-click on the ex_description.h to open it in the editor.

As soon as you try to edit the ex_description.h, you will be presented a Warning indicating you are editing an SDK file. Click on Edit in SDK.

Remove the following #define in ex_decription.h

#define  RTOS_MODULE_USB_DEV_HID_AVAIL

Add the following #define in ex_description.h to indicate Micrium OS that you want to use CDC-ACM class.

#define  RTOS_MODULE_USB_DEV_ACM_AVAIL

Adding USBD Class and Demo

Expand the src section in the Project Explorer panel and remove the ‘ex_usbd_hid_mouse.c’ linked file.

Select Import > MCU Project by right-clicking on src section as shown on image below

Choose ‘More Import Options…’  and select File System  on the next window that pops-up as shown on the images below

Use Browse button and add ‘ex_usbd_cdc_acm_terminal.c’ example as shown on image below, and click Finish.

File location: `C:\SiliconLabs\SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\v2.4\app\micrium_os_example\usb\device\all`

Expand the usb>source>device>class section in the Project Explorer  panel and right-click on class. Select Import > MCU Project  and add the USBD CDC ACM class file as shown on images below

Use the Browse button to locate the CDC-ACM files to be added as shown below.

File location: `C:\SiliconLabs\SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\v2.4\platform\micrium_os\usb\source\device\class`

Running the Example

You can now build your application and flash it on the board. Once the application starts running, you should see LED0 on the board blinking which means all the initialization was done correctly; therefore, we can now test the USBD CDC-ACM demo.

Open Windows Device Manager and expand the 'Ports (COM & LPT)' section. 

Use a Micro-USB B cable to connect the PC to the EFM32GG11 board. As soon as you connect it, Windows will enumerate the device and display it in 'Ports (COM & LPT)' as shown in the image below. Keep in mind that Windows is the one assigning the port number (COM7)  to my device.

Once you know the serial port number, we can use any serial terminal application and  open a terminal window.  The images below shows the terminal configurations and the CDC-ACM demo output.

Background

The Micrium OS Examples in Simplicity Studio are very easy to access: You connect your Starter Kit and Simplicity Studio will display the list of examples as shown below:

For more information on how to access the Micrium OS Examples from Simplicity Studio you can see this document:

https://www.silabs.com/documents/public/training/wireless/micrium-os-examples.pdf

Revealing the 57 Hidden Gems

In this blog, I’m going to show you how to access the additional Micrium OS Examples that are not available from Simplicity Studio's Launcher Perspective.

There are 57 examples that demonstrate how to initialize the Micrium OS modules to perform the most basic operations:

How to run the hidden Micrium OS Examples

The process of including, configuring and initializing the examples is the same for all the examples and can be summarized as follows:

Start off with one of the examples available through Simplicity Studio by connecting your Kit and selecting an Example from the list as illustrated in Figure 1.

If the example project does not have the Micrium OS module files, then you need to include them by inserting in your project the folder located at ${StudioSdkPath}/platform/micrium_os/[module]/include and ${StudioSdkPath}/platform/micrium_os/[module]/source/[module] and configuring your compiler's include paths with the new paths.

Locate the header file rtos_description.h and insert the macro necessary to enable the module. For the full list of macros see this document.

Make sure you have in your project all the configuration files located in STUDIO_SDK_LOC\platform\micrium_os\cfg

Explore the examples listed in Table 1, select the one that you want and follow the corresponding hyperlink.

       The hyperlink will take you to the example's documentation which provides four things:

• Description: Brief description of the example
• Configuration: The name of the #define that needs to be defined in ex_description.h
• Location: The location of the files that need to be included
• API: The API that needs to be called from your application to start the example

Locate the header file ex_description.h and define the corresponding macro if necessary as described in the example's documentation section: Configuration.

Include in your Simplicity Studio project the required files as listed in the example's documentation section: Location. In this step you can either create a link to the original folder or make a copy of the files and place them in your own workspace directory.

Configure your compiler's include paths with the new paths where the header files are located.

Insert a #include in your application, of the header file where the API to start the example is declared and call the API from your application to get the example started as described in the example's documentation section: API.

Example

To illustrate the process, I'm going to provide an example where one is interested in running an HTTP server:

Connect the SLSTK3701A and select the example SLSTK3701A_micriumos_net from Simplicity Studio.

Inspect which modules are included in the project by looking at the folder net in the Project Explorer. There you will notice that the module HTTP Server is missing.

Include the HTTP Server module by creating a new Linked Folder located at STUDIO_SDK_LOC\platform\micrium_os\net\source\http\server

Open the new folder Properties and either include or exclude the folder from compilation as necessary from the section C/C++ Build.

Open the Project Properties and insert the location to the new header files ${StudioSdkPath}/app/micrium_os_example/net/http/server in the section C/C++ General -> Paths and Symbols

Locate and open the header file rtos_description.h and insert the following line to enable the new HTTP Server Module: #define  RTOS_MODULE_NET_HTTP_SERVER_AVAIL

Copy the configuration files from STUDIO_SDK_LOC\platform\micrium_os\cfg to your own workspace directory and make sure the compiler is aware of this include path.

Look at Table 1, locate the Example Basic Server That Uses the HTTP Static File System and explore the documentation.

Open the header file ex_description.h and insert the following line to enable the example: #define  EX_HTTP_SERVER_INIT_AVAIL

Create a new Folder named Examples and then create a Linked Folder in it that points to STUDIO_SDK_LOC\app\micrium_os_example\net\http\server

Open the Project Properties and insert the path ${StudioSdkPath}/app/micrium_os_example/net in the section C/C++ General -> Paths and Symbols

Open the file ex_main.c and insert the following line at the top: #include  "http/server/ex_http_server.h"

From the same file ex_main.c, locate the calls to the functions Ex_NetworkInit() and Ex_Net_CoreStartIF() and insert right after them, a call the following API to get the example started: Ex_HTTP_Server_InstanceCreateStaticFS();