Silicon Labs AN1260, RTOS User Manual
AN1260: Integrating v3.x Silicon Labs
Bluetooth® Applications with Real-Time
Operating Systems
This application note provides background information on the
system architecture and event-based communication between a
real-time operating system (RTOS) and the Bluetooth application.
It then discusses user-defined tasks and describes how to customize an application.
KEY POINTS
• Prerequisites
• System architecture, Inter-task
communication and task descriptions
• Application integration using specific
example tasks
• Customization the application
• Additional resources
silabs.com | Building a more connected world. Rev. 0.3
AN1260: Integrating v3.x Silicon Labs Bluetooth® Applications with Real-Time Operating Systems
Introduction
1. Introduction
This application note describes how to integrate a v3.x Silicon Labs Bluetooth application with an RTOS (real-time operating system),
using the SOC-Empty example in Simplicity Studio 5 as an illustration. As of Silicon Labs Bluetooth SDK version 3.1.0, the adaptation
layer has been designed to work with Micrium OS RTOS and FreeRTOS, both using the CMSIS-RTOS2 API. To work with any other
RTOS, the OS should have the following features:
• Tasks with priorities
• Flags for triggering task execution from interrupt context
• Mutexes
The solution places the handling of Bluetooth stack events into its own task, allowing the application to run other tasks when no Bluetooth events are pending. When no tasks are ready to run, the application will sleep.
1.1 Prerequisites
You should have:
• A general understanding of RTOS concepts such as tasks, semaphores and mutexes.
• A working knowledge of Bluetooth Low Energy communications.
• A Wireless starter kit with an EFR32BG or EFR32MG radio board
• Installed and be familiar with using the following:
• Simplicity Studio 5
• IAR Embedded Workbench for ARM (IAR-EWARM) (optional - only use the version that is compatible with the SDK version, as
listed in the SDK release notes). May be used as a compiler in the Simplicity Studio development environment as an alternative
to GCC (The GNU Compiler Collection), which is provided with Simplicity Studio. Again, use only the GCC version that is compatible with the SDK version, as listed in the SDK release notes.
• Bluetooth SDK v3.1.0 or above
If you need to familiarize yourself with any of these concepts, the following may be useful:
• UG103.14: Bluetooth® LE Fundamentals
• QSG169: Bluetooth® SDK v3.x Quick Start Guide
• µC/OS-III User Manual for an overview of RTOS fundamentals
• FreeRTOS
• RTOS Fundamentals
• FreeRTOS Kernel Developer Docs
silabs.com | Building a more connected world. Rev. 0.3 | 2
AN1260: Integrating v3.x Silicon Labs
Bluetooth® Applications with Real-Time Operating Systems
Introduction
1.2 Micrium OS Configuration
To have Micrium RTOS run in your application, the Micrium OS Kernel component needs to be added to your application project. The
following procedure illustrates this using the SOC-Empty example project.
1. Double-click the soc_empty.slcp file in the Simplicity Studio Project Explorer to open the Project Configurator, and click the
SOFTWARE COMPONENTS tab.
2. Enter micrium in the search field in the top right corner. Optionally, select the Configurable Components checkbox to shorten the
component list.
3. Select Micrium OS Kernel in the left pane and click Install .
The Micrium OS Kernel component adds Micrium RTOS support to the SOC-Empty example project and configures the project to run
the Bluetooth stack in multiple tasks. These tasks are discussed in section 2. System Architecture.
The following components are added automatically when adding the Micrium OS Kernel component:
Generic RTOS related:
• Platform - CMSIS - CMSIS-RTOS2
• Platform - CMSIS - CMSIS-RTOS2 Headers
• Platform - Common - Common APIs for CMSIS-Compliant Kernels
Micrium OS related:
• RTOS - Micrium OS - Common - CPU - Micrium OS CPU Module
• RTOS - Micrium OS - Common - Micrium OS Common Module Core
• RTOS - Micrium OS - Common - RTOS Description
• RTOS - Micrium OS - Kernel - Micrium OS Kernel
Note: If the component Simple timer service is used in the application, a separate version for the Micrium OS called Simple timer
service for Micrium RTOS should be used instead.
silabs.com | Building a more connected world. Rev. 0.3 | 3
AN1260: Integrating v3.x Silicon Labs
Bluetooth® Applications with Real-Time Operating Systems
Introduction
1.3 FreeRTOS Configuration
To have FreeRTOS run in your application, add the FreeRTOS component and the preferred FreeRTOS Heap component (Heap 3 is
used in the examples) to your application project.
To add the FreeRTOS component to the SOC-Empty example project:
1. Double-click the soc_empty.slcp file in the Simplicity Studio Project Explorer to open the Project Configurator, and click the
SOFTWARE COMPONENTS tab.
2. Enter freertos in the search field in the top right corner.
3. Select FreeRTOS Heap 3 in the left pane and click Install.
The FreeRTOS Heap 3 component adds FreeRTOS support to the SOC-Empty example project and configures the project to run the
Bluetooth stack in multiple tasks. These tasks are discussed in section 2. System Architecture.
Note: If the FreeRTOS component is added instead of the FreeRTOS Heap 3 component, it will default to FreeRTOS Heap 4. To see
more information about the FreeRTOS heap implementations, see the FreeRTOS documentation.
The following components are added automatically when adding the FreeRTOS Heap 3 component:
Generic RTOS related:
• Platform - CMSIS - CMSIS-RTOS2
• Platform - CMSIS - CMSIS-RTOS2 Headers
• Platform - Common - Common APIs for CMSIS-Compliant Kernels
FreeRTOS related:
• RTOS - FreeRTOS - FreeRTOS
• RTOS - FreeRTOS - FreeRTOS Heap 3
Note: If the component Simple timer service is used in the application, there are special versions for the FreeRTOS called Simple
timer service for FreeRTOS and Simple timer service for FreeRTOS with static memory allocation.
silabs.com | Building a more connected world. Rev. 0.3 | 4
AN1260: Integrating v3.x Silicon Labs Bluetooth® Applications with Real-Time Operating Systems
System Architecture
2. System Architecture
The SOC-Empty example application with Micrium RTOS or FreeRTOS support requires several tasks in order to operate
• Link Layer Task
• Bluetooth Host Task
• Event Handler Task
• Idle Task
Silicon Labs has implemented these tasks for the Micrium RTOS and FreeRTOS.
silabs.com | Building a more connected world. Rev. 0.3 | 5
AN1260: Integrating v3.x Silicon Labs
Bluetooth® Applications with Real-Time Operating Systems
System Architecture
2.1 Inter-Task Communication
Before describing the tasks, it is important to understand how the tasks communicate with each other. The tasks in this application synchronize with each other through the use of a number of flags. The flags are internal of the sl_bt_rtos_adaptation layer. These flags are
summarized in the following table:
FLAG Sender Receiver Purpose
SL_BT_RTOS_EVENT_FLAG_STACK
SL_BT_RTOS_EVENT_FLAG_LL
SL_BT_RTOS_EVENT_FLAG_CMD_WAITING
SL_BT_RTOS_EVENT_FLAG_RSP_WAITING
SL_BT_RTOS_EVENT_FLAG_EVT_WAITING
SL_BT_RTOS_EVENT_FLAG_EVT_HANDLED
Link Layer
Task
Radio Interrupt
Event Handler
and Application Tasks
Bluetooth
Host Task
Bluetooth
Host Task
Event Handler
Task
Bluetooth
Host Task
Link Layer
Task
Bluetooth
Host Task
Event Handler
and Application Tasks
Event Handler
Task
Bluetooth
Host Task
Bluetooth stack needs an update, call
sl_bt_pop_event()
Link Layer needs an update, call sl_bt_priority_handle()
Command is ready in shared memory, call
sli_bt_cmd_handler_delegate()
Response is ready in shared memory.
Event is ready in shared memory.
Event is handled and shared memory is free to use
for next event.
The following diagram illustrates how these flags are used in synchronizing the tasks.
In addition to these flags, a mutex is used by the gecko command handler to make it thread-safe. This makes it possible to call BGAPI
commands from multiple tasks.
2.2 Link Layer Task
The purpose of this task is to update the upper link layer. The link layer task waits for the SL_BT_RTOS_EVENT_FLAG_LL flag to be set
before running. The upper link layer is updated by calling sl_bt_priority_handle(). The SL_BT_RTOS_EVENT_FLAG_LL flag is set by
sli_bt_rtos_ll_callback(), which is a callback function specified to scheduler_callback in the stack configuration. The callback is
called from a kernel-aware interrupt handler (lower link layer). This task is given the highest priority.
silabs.com | Building a more connected world. Rev. 0.3 | 6
AN1260: Integrating v3.x Silicon Labs Bluetooth® Applications with Real-Time Operating Systems
System Architecture
2.3 Bluetooth Host Task
The purpose of this task is to update the Bluetooth stack, issue events, and handle commands. This task waits for any of the
SL_BT_RTOS_EVENT_FLAG_STACK, SL_BT_RTOS_EVENT_FLAG_CMD_WAITING and SL_BT_RTOS_EVENT_FLAG_EVT_HANDLED flags to be set
before running. The SL_BT_RTOS_EVENT_FLAG_STACK flag is set by sli_bt_rtos_stack_callback(), which is a callback function
specified to stack_schedule_callback in the stack configuration. This task has higher priority than the Event Handler Task and any of
the Application Tasks, but lower than the Link Layer Task.
Before this task starts running, it prepares the application to run the Bluetooth stack. This task calls sl_bt_init() to initialize and configure the Bluetooth stack, and then calls sl_bt_rtos_create_tasks() to create the Link Layer Task and Event Handler Task.
2.3.1 Updating the Stack
The Bluetooth stack must be updated periodically. The Bluetooth Host Task updates the stack by calling sl_bt_event_pending() and
reads the next stack event from the stack by calling sl_bt_pop_event(). This allows the stack to process messages from the link layer
as well as its own internal messages for timed actions that it needs to perform.
2.3.2 Issuing Events
The Bluetooth Host Task sets the SL_BT_RTOS_EVENT_FLAG_EVT_WAITING flag to indicate to the event handler task that an event is
ready to be retrieved. Only one event can be retrieved at a time. The SL_BT_RTOS_EVENT_FLAG_EVT_WAITING flag is cleared by the
Event Handler Task when it has retrieved the event. The SL_BT_RTOS_EVENT_FLAG_EVT_HANDLED flag is set by the Event Handler Task
to indicate that event handling is complete.
silabs.com | Building a more connected world. Rev. 0.3 | 7
AN1260: Integrating v3.x Silicon Labs
Bluetooth® Applications with Real-Time Operating Systems
System Architecture
2.3.3 Command Handling
Commands can be sent to the stack from multiple tasks. Responses to these commands are forwarded to the calling task. Commands
and responses are synchronized with the SL_BT_RTOS_EVENT_FLAG_CMD_WAITING and SL_BT_RTOS_EVENT_FLAG_RSP_WAITING flags
and the BluetoothMutex mutex.
Commands are prepared and sent to the stack by a helper function called sli_bt_cmd_handler_rtos_delegate(). This function is
called by any of the BGAPI functions and is made re-entrant through the use of a mutex. The function starts by pending on the mutex.
When it gains control of the mutex the command is prepared and placed into shared memory, then the
SL_BT_RTOS_EVENT_FLAG_CMD_WAITING flag is set to indicate to the stack that a command is waiting to be handled. This flag is cleared
by the Bluetooth Host Task to indicate that the command has been sent to the stack and that it is now safe to send another command.
Then execution pends on the SL_BT_RTOS_EVENT_FLAG_RSP_WAITING flag, which is set by the Bluetooth Host Task when the command
has been executed. This indicates that a response to the command is waiting. Finally, the mutex is released.
The following diagram illustrates how the Bluetooth Host Task operates.
1. On task startup, the SL_BT_RTOS_EVENT_FLAG_STACK is set to indicate that the stack needs updating and the
SL_BT_RTOS_EVENT_FLAG_EVT_HANDLED flag is set to indicate that no event is currently being handled.
silabs.com | Building a more connected world. Rev. 0.3 | 8
Loading...