SimpleLink MCU SDK User's Guide
Table of Contents
Introduction to SimpleLink™ MCU SDK
The SimpleLink™ MCU Software Development Kits (SDK) contain software development tools that enable engineers to develop applications on a range of microcontroller families from Texas Instruments. The SDK is provided as separate installations optimized for each SimpleLink microcontroller family. These versions of the SDK share most components and are engineered to support the creation of portable applications. These powerful software toolkits provide a cohesive and consistent software experience by packaging essential software components and easy-to-use examples in one easy-to-use software package.
If you have not already installed the SDK and performed the initial setup steps, see the Quick Start Guide.
Documentation and Support
Links to documentation for the SDK and its components are provided in the Documentation Overview.
The SimpleLink Academy provides step-by-step workshops and video tutorials that introduce many of the components of the SimpleLink SDK.
This SDK is supported on the TI E2E™ Community.
SDK Components
The SDK components are used together to build applications. The SDK components relate to each other as shown in the following diagram.
Starting from the bottom of this architecture diagram, the components are as follows:
- Hardware: The TI SimpleLink family:
- MSP432 High-precision ADC MCU (MSP432P4): Low-power MCUs built around an ARM Cortex M4 core and optimized for Internet-of-Things sensor nodes.
- MSP432 Ethernet Microcontrollers (MSP432E4): High-performance ARM Cortex-M4F MCUs optimized for wired and wireless connectivity and algorithm processing. Includes integrated Ethernet MAC and PHY and other wired communication interfaces.
- CC32xx: ARM Cortex M4-based MCUs with integrated WiFi and security features.
- CC26xx/CC13xx: Low-power wireless ARM Cortex M3-based MCUs for high performance RF applications. These devices support a range of wireless standards.
- Hardware Abstraction Layer (HAL): C functions that abstract writes to hardware registers. This is the layer the drivers and OS kernel use to access hardware features. Certain hardware settings can be configured using the SysConfig tool.
- OS/Kernel: The kernel provides services such as timing and scheduling of tasks. All TI SimpleLink SDKs come with the TI-RTOS Kernel. Some SDKs also support alternative RTOS kernels (such as FreeRTOS). Using a kernel is optional; the SDK also supports the “NoRTOS” option, which allows TI Drivers to be used with no underlying OS.
- The Driver Porting Layer (DPL) abstracts driver interfaces. Drivers use RTOS features such as clocks, interrupts, mutexes, and semaphores. By abstracting this functionality, applications that use TI Drivers are not dependent on the TI-RTOS Kernel and can instead use the FreeRTOS kernel or no RTOS.
- The POSIX layer abstracts the RTOS kernel functionality used by applications. The POSIX layer allows examples and user applications to be easily ported to use a different kernel. Using this layer is optional. (See “Choosing Whether to Use POSIX.”)
- TI Drivers API: Exposes functionality of the hardware-specific drivers in the same way across all TI SimpleLink devices. Though the hardware implementation of the UART may be different on different chipsets, the TI Drivers API used to access its common functionality is the same. TI Drivers can be configured manually or using the SysConfig tool.
- Middleware: Add functionality on top of drivers. Communications stacks and graphics libraries are examples of middleware.
- Examples: The SDK provides a wide range of examples. Their purpose is to make it easy to start writing applications. Each example comes with its own documentation and project files. Examples are provided that use the supported RTOS kernels. For certain SDKs, examples that do not use an RTOS are also provided.
Directory Structure
The SDK is installed in /ti
or c:\ti
by default. This is also the installation location for any plug-ins that are installed alongside the SDK. This is the top-level directory structure of the SDK installation:
- The “docs” directory contains all the documentation files for the various SDK components. The Documentation Overview links to these documents.
- The “examples” directory contains a number of example applications for each supported board.
- The “kernel” directory contains the files required to use the TI-RTOS Kernel and the FreeRTOS kernel. The kernels implement the DPL and POSIX layers, which allow an SDK application to switch between the supported kernels.
- The “source” directory contains source code, libraries, and linker files used when building applications. This includes files for drivers, boards, devices, middleware, and more. For example, the source code for all the TI Drivers is provided here. See the following figure for more about the contents of this directory tree.
Since the same directory structure is used across the different SDKs in the TI SimpleLink family, it is possible to move application code between the different devices without making significant changes to the file structure or include paths.
The following figure shows a high-level view of the “source” directories that are common to all device types. The SDK provides additional features for specific device families.
The following figure similarly provides an overview of the “examples” directory contents that are common to all device types.
- See the SysConfig section for information about the examples in the “syscfg_preview” tree.
Tools and Utilities Not Included
The SDK does not contain an IDE or code generation tools such as a compiler and linker. You should have one of the supported code generation tool suites available. The supported suites are Code Composer Studio with TI’s Code Generation Tools, IAR Workbench with its compilers, and the GNU Compiler Collection (gcc).
The SDK does not install FreeRTOS. You can download the FreeRTOS source files via the FreeRTOS website. Refer to the SimpleLink Core SDK Release Notes for information about supported versions of FreeRTOS. The SDK does install the Driver Porting Layer (DPL) and POSIX abstractions to allow FreeRTOS to be used with the other SDK components.
The SDK does install XDCtools, which includes configuration tools for the TI-RTOS Kernel. The XDCtools component contains the underlying tools and modules used by TI-RTOS and its kernel. When you install the SDK, XDCtools is installed in a parallel directory at the same level as the SDK’s installation directory.
Some versions of the SDK also offer functionality-specific tools, such as the BTool for interfacing with the TI Bluetooth Low Energy (BLE) stack from a PC.
Understanding a SimpleLink MCU SDK Application
There are three different project layouts with the SimpleLink MCU SDK’s examples:
- Stand-alone project: These projects contain the entire application.
- Application project + kernel project: The kernel application is brought in automatically when importing the application project. The application uses contents (such as libraries) from the kernel project.
- Application project + BLE stack project: For devices that support BLE (such as CC13xx/CC26xx), the BLE stack project is brought in automatically when importing the application project. The application and stack binaries both need to be loaded to the target. Please refer to the BLE’s Quick Start Guide for more details.
The SimpleLink MCU SDK provides an example called demos\portable
that serves as an introduction to creating your own applications using the SDK. This example is comprised of an application project and a kernel project. The example uses the UART and I2C drivers and low-power states. It illustrates multi-tasking, I/O drivers, and low-power states. The code uses POSIX so that it is easy to run the example using either the TI-RTOS Kernel or the FreeRTOS kernel.
The application has the following functionality.
- Initializes the UART driver in blocking read and write mode.
- The
consoleThread
thread provides a simple console. When the UART is closed, the device can go into a lower-power state. - The
temperatureThread
thread reads the temperature from a peripheral device via the I2C driver.
The “portable” example is located in the <SDK_INSTALL_DIR>\examples\syscfg_preview\rtos\<board>\demos\portable
directory. It is available for all supported boards, RTOS kernels, toolchains, and IDEs.
Importing, Building, and Running the Example
Import the example as described in the Quick Start Guide. Separate instructions are provided there for the Code Composer Studio (CCS) IDE, IAR Embedded Workbench, makefiles using the GCC compiler, and other supported development environments. Follow the instructions in the “Execute your First Application” section of the Quick Start Guide for your development environment, but choose the “portable” example for your board, RTOS (TI-RTOS or FreeRTOS), and compiler.
Build the “portable” example as described in the same section of the Quick Start Guide.
A README.html
file is included with the example files you imported. View this file and follow the instructions in the “Example Usage” section to run the example.
For boards other than CC32XX, you’ll need the Sensors BoosterPack Module, which contains a TMP116 temperature sensor.
For CC32XX boards using CCS, let the device “Free Run” instead of “Run.”
Understanding the Example
This section examines the “portable” example’s code to understand how it was created.
To see how the example supports multiple IDEs and RTOS kernels, it is best to look at the example files in the SDK installation. The process of importing an example removes files used to support other IDEs and RTOS kernels than the one you are using.
Go to your <SDK_INSTALL_DIR>\examples\syscfg_preview\rtos\<board>\demos\portable
directory.
The example contains the following source files:
- main_tirtos.c and main_freertos.c: These files contain the main() function. They are located in subdirectories and use POSIX (pthread) calls to initialize drivers and create the threads that will run the
consoleThread
and thetemperatureThread
threads. - console.c: This file contains the function run by the
consoleThread
thread along with the callback function for the GPIO interrupt run when the board BUTTON1 is pressed. - temperature.c: This file contains the function run by the
temperatureThread
thread. - portable.syscfg: Each example has a SysConfig file, which is used to configure board-specific items, such as pins and attributes for the various TI Drivers. For example, for the UART driver, properties such as the clock source and pins used are configured. This file will be used to generate Board.c and Board.h files used when building the application.
(The remaining files provide documentation for the example and a default Runtime Object View layout.)
The following sections examine these parts of the application in more detail. Open the code files as you read these sections to better understand how an application uses the SDK.
main_tirtos.c and main_freertos.c
The two versions of the main() function are mostly identical. Because POSIX Pthreads are used instead of direct calls to kernel APIs, only minor differences are needed to run the TI-RTOS Kernel or the FreeRTOS kernel.
Header Files
Both versions of the file #include the following files:
stdint.h
pthread.h
ti/drivers/GPIO.h
(this is a TI-RTOS package path, which locates the file within<SDK_INSTALL_DIR>/source
)Board.h
The FreeRTOS version of the file also includes FreeRTOS.h
and task.h
.
The TI-RTOS version of the file also includes ti/sysbios/BIOS.h
, which in this case locates the file within <SDK_INSTALL_DIR>/kernel/tirtos/packages/ti/sysbios
.
The main() Function
- The main() function begins by calling Board_initGeneral(), which the board.h file defines to point to a board-specific function in the board.c file.
- The function then sets various thread attributes in the
attrs
structure:- It calls pthread_attr_setdetachstate() with the PTHREAD_CREATE_DETACHED state to cause the threads created to be in the detached state, since the threads used by this application will never need to join with another thread.
- It calls pthread_attr_setschedparam() to set the default scheduling priority for the threads to 1 (the minimum priority).
- It calls pthread_attr_setstacksize() to set the size of the thread’s stack to the value defined for the THREADSTACKSIZE constant, which is defined as a size in bytes earlier in the same file.
- The main() function then calls pthread_create() twice.
- The first time it creates a thread that will run the consoleThread() function. This thread runs at the default priority (1, which is the minimum). (See the console.c file for actions performed by this thread.)
- The second time it creates a thread that will run the temperatureThread() function. This thread is set to a higher priority (2) than consoleThread. As a result, if both threads are ready to run, the temperatureThread runs first. The console thread runs when the temperature thread is blocked or waiting for data from the I2C transfer. (See the temperature.c file for actions performed by this thread.) For example:
See the TI-POSIX User’s Guide for details about which POSIX APIs are supported by the SDK.priParam.sched_priority = 2; pthread_attr_setschedparam(&attrs, &priParam); retc = pthread_create(&thread, &attrs, temperatureThread, NULL); if (retc != 0) { /* pthread_create() failed */ while (1); }
- The main() function then creates a mutex that will be used to protect the temperature variables from unsafe updates by the consoleThread() and temperatureThread().
- Next the main() function called GPIO_init() to initialize the GPIO driver. This initialization is performed in main() because both threads will use the GPIO driver.
- At this point, the two versions of the main() function diverge.
- The TI-RTOS Kernel version simply calls BIOS_start() to start the scheduler. BIOS_start() does not return.
- The FreeRTOS version calls vTaskStartScheduler() to start the FreeRTOS scheduler. vTaskStartScheduler() does not return.
Note: A “portableNative” variant of the “portable” example is provided for both TI-RTOS and FreeRTOS. These examples call the TI-RTOS Kernel or FreeRTOS APIs directly, instead of calling the POSIX APIs. Using the RTOS APIs directly saves both code and data memory. The only code differences for these native RTOS examples are located in the application source files: main_tirtos.c, main_freertos.c, console.c, and temperature.c.
For example, the TI-RTOS Kernel version of the portableNative example calls the Task_create() API instead of the pthread_create() API code shown in Step 3 as follows:
Task_Params_init(&taskParams);
taskParams.priority = 2;
taskParams.stackSize = 768;
temperatureTaskHandle = Task_create(temperatureThread, &taskParams, &eb);
See the TI-RTOS Kernel User’s Guide for more about the TI-RTOS Kernel APIs.
console.c
This file is identical for all boards, RTOS kernels, and development environments. Remember to see the README.html file for information about how to open a serial session to run the example’s console.
The consoleThread() function runs when the RTOS scheduler starts. First it performs some setup tasks. Later it drops into a while loop that runs until the application is halted.
Within the setup portion of the function, the consoleThread() function performs these actions:
- Enables the Power Manager for CC32XX boards, because power management is disabled by default on the CC32XX for easier debugging.
- Configures Board_GPIO_BUTTON1 to run the gpioButtonFxn() to wake the board in response to a button press.
- Calls the POSIX function sem_init() to initialize an unnamed semaphore. The button press posts the semaphore and the while loop later in the consoleThread() function waits on the semaphore.
- Initializes the parameters for the UART communication.
Within the while loop, the consoleThread() function performs these actions:
- If uartEnabled is false (which happens when the console is closed), waits on the semaphore until the button is pressed.
- Opens a UART for the console in blocking read and write mode by setting parameters and then calling UART_open().
Runs the simpleConsole() function, which uses UART_write() and UART_read() to manage the console’s user interface, which accepts the following commands:
Valid Commands -------------- h: help q: quit and shutdown UART c: clear the screen t: display current temperature
- If the “t” command is used, the values of both the
temperatureC
andtemperatureF
external variables provided by the temperatureThread are stored locally. A mutex is used to protect these operations. Without the mutex, the temperature thread, which has a higher priority, could interrupt the reading of the variables by the console thread. The result could be that the console thread printed a Celsius value that did not match the Fahrenheit value. - The static itoa() function is used to convert the integer temperature values to strings, and UART_write() is used to output the values to the console.
If the “q” command is used, the simpleConsole() function returns and the UART_close() is called. The Power Manager automatically goes to a lower-power state when the UART is closed. See the TI-RTOS Power Management User’s Guide for more about power states.
temperature.c
This file is identical for all boards, RTOS kernels, and development environments.
The temperatureThread() function runs when the RTOS scheduler starts. First it performs some setup tasks. Later it drops into a while loop that runs until the application is halted. The thread blocks on a semTimer semaphore at the end of the while loop. A timer running at one second posts the semTimer semaphore to unblock the task. A sleep() function could have been used, but a very small amount of drift would have occurred.
Within the setup portion of the function, the temperatureThread() function performs these actions:
- Initializes the I2C driver and opens the driver for use.
- Initializes the I2C_transaction structure that will be used in the I2C_transfer().
- Initializes the timer and semTimer semaphore.
Within the while loop, the temperatureThread() function performs these actions:
- If an I2C transfer succeeds, a mutex is locked to make the operations that follow thread safe.
- The temperature is extracted from the received data. (For CC32XX boards, the default is to read the temperature from the onboard TMP006 or TMP116 sensor. For all other boards, the example reads the temperature from the TMP116 sensor on the Sensors BoosterPack.)
- The temperature is scaled to be accurate in Celsius degrees and is also converted to Fahrenheit. Both values are stored for output.
- The mutex lock is released.
- If the temperature is higher than 30 C, an alert message is written using GPIO_write(). Otherwise, any previous alert message is cleared.
- The while loop blocks on the semTimer semaphore, which will be posted every second by the timer created by the thread. If the UART is closed, this provides enough time for the device to transition to a lower-power state under the control of the Power Manager.
Note: For details about achieving better power savings on the MSP432P4 by using the Watchdog timer, see the TI-RTOS MSP432 Timer wiki topic.
portable.syscfg
This file specifies how SysConfig should be used to set up board-specific items. For example, the GPIO section configures the GPIO input pins, output pins, and LEDs. It creates an array of callback functions for the input pins and sets them to NULL. For each driver, it declares a configuration structure and sets the defaults for the attribute fields in the structure.
When the example is built, this file will be used to generate Board.c
and Board.h
files, which configure the structures used by the TI Drivers. These structures are similar for most TI Drivers. For example, a configuration data structure called <Driver>_Config
is defined. Each driver’s configuration includes a pointer to a function table, a pointer to an object, and a pointer to a set of hardware attribute settings. For more about the driver configuration structures, see the detailed reference information for the TI Driver APIs.
Note: Use of SysConfig is currently optional and requires additional installation steps. If you wish, you may continue to configure TI Drivers and device pins using the board files. Examples are provided for both methods of configuration.
Files for CCS, GCC, and IA
For each supported RTOS, the example contains files that are used to set up a project for the example when you import the example into a development environment. Projects for Code Composer Studio (CCS), IAR Embedded Workbench, and the GNU Compiler Collection (GCC) can be created.
Making Choices for Your Application
When using the SDK to create your own application, you should begin by making the following choices:
- Choosing which hardware target to use? See the list in SDK Components.
- Choosing which development environment to use? See Choosing a Development Environment.
- Choosing which RTOS to use? See Choosing an RTOS.
- Choosing whether to use POSIX APIs? See Choosing Whether to Use POSIX.
- Choosing which driver access method to use? See Choosing a Driver Access Method.
Choosing a Development Environment
Choose your preferred development environment. The SimpleLink MCU SDK supports all of the following development environments equally well:
- TI’s Code Composer Studio (CCS)
- IAR Embedded Workbench
- GNU Compiler Collection (gcc)
The SDK examples can be imported into any of these environments as described in the Quick Start Guide.
Choosing an RTOS
You may use either the TI-RTOS Kernel or FreeRTOS with SDK applications that use the TI Drivers. Or, you can use the NoRTOS option, which allows you to use the TI Drivers without an underlying operating system (OS).
The TI-RTOS Kernel is a scalable real-time kernel. It is designed to be used by applications that require real-time scheduling and synchronization or real-time instrumentation. It provides preemptive multi-threading, hardware abstraction, real-time analysis, and configuration tools. The Kernel is designed to minimize memory and CPU requirements on the target. The TI-RTOS Kernel was previously called SYS/BIOS. It is described in the TI-RTOS Kernel User’s Guide. The Texas Instruments Wiki also links to training videos and more.
FreeRTOS is an open-source, real-time operating system kernel for embedded devices. It implements a minimalist set of functions, basic task handling and memory management. If you want to use the native FreeRTOS routines without the abstractions provided by the SDK, see the FreeRTOS website. Note: FreeRTOS is not supported for the CC13xx or CC26xx device families, since these devices use TI-RTOS in ROM.
NoRTOS enables the use of the TI Drivers without an underlying operating system (OS). Since there is no OS in this scenario, there can only be one main thread. Interrupts can preempt this main thread, but typical “multithreading” is not available.
Choosing Whether to Use POSIX
To enable re-use of code across the TI-RTOS and FreeRTOS kernels, the SDK provides a POSIX layer.
All of the kernel-based driver examples in the SDK are POSIX-based (except the portableNative examples). This allows the same code to be shared by the applications using the TI-RTOS and FreeRTOS kernels. If you want your applications to have this type of portability across kernels, we recommend that you use POSIX.
However, not all kernel features are available in the POSIX interface. If you need any OS-specific feature that is not available in the POSIX implementation, you can use a direct OS call during part of the application or the entire application.
See the TI-POSIX User’s Guide for details about which POSIX APIs are supported.
Choosing a Driver Access Method
You can choose a driver access method to fit the needs of that application. Factors that can be used to determine which method to use include:
- Does the application use TI-RTOS or FreeRTOS? Both kernels enable the use of TI Drivers.
- Do you want portability across MCUs? We recommend using the TI Drivers in this case.
- Would you like the method to provide resource allocation and abstracted power management? TI Drivers provides these features.
- Do you need to access device-specific features? Driverlib is recommended for device-specific programming. The Driverlib APIS are well-tested and are often available in ROM. They also provide an easy abstraction model for device-specific programming.
- If access to a desired feature is not available in Driverlib, or if you want full control over the registers, we recommend using the Register Access method.
You can use a combination of access methods. For example, you can use TI Drivers and Driverlib together. However, be aware that power management and resource allocation differ between access methods. For this reason, resource conflicts can arise. As long as you remain aware of the issues when using multiple access methods, it is possible to use the best features of each one.
TI Drivers
The TI Drivers provide an API interface that is compatible across the supported MCUs. Your applications can use this API with either the TI-RTOS or FreeRTOS kernel (or no RTOS).
In order to provide a cross-MCU compatible set of APIs, some device-specific features are not available in the TI Drivers. Instead, the focus is on ease of migration. The TI Drivers abstract the common features rather than providing feature-completeness.
Driverlib
Driverlib provides device-specific APIs that abstract register and peripheral details. The goal is to provide most (if not all) of the features of the device or peripheral at an abstracted API level. Since APIs and features are closely tied to the hardware, it may not be easy to migrate the application code from one MCU to another.
This API interface provides an abstracted way to configure hardware registers. This access method acts as a translation layer for setting/resetting a register bit or set of register bits.
Register Access
This access method configures hardware registers directly by setting/resetting specific bit combinations. This method provides 100% feature coverage with no abstraction at all.
When using this method, refer to the Device Family Technical Reference Manual and the Device Datasheet. Set and reset specific bits in the registers using the definitions in the device header files included with the SDK.
TI Drivers
The SDK includes drivers for a number of peripherals. These drivers are provided in the <SDK_INSTALL_DIR>/source/ti/drivers
directory. The driver examples show how to use these drivers.
Some of the drivers are available only for certain target families. Some examples of drivers supported on several target families include GPIO, I2C, Power, SPI, UART, and Watchdog. There are many more. See the detailed reference information for the complete list of TI Drivers for your target family along with full information about the APIs and configuration structures.
Driver Framework
TI drivers have a common framework for configuration and a set of APIs that all drivers implement. Applications interface with a TI driver using a top-level driver interface. This interface is configured via a set of data structures that specify one or more specific lower-level driver implementations. TI Drivers can be configured manually or using the SysConfig tool.
TI drivers all implement the following APIs (with a few exceptions).
Void Driver_init(Void)
— Initializes the driver. This function must be called only once and before any calls to the other driver APIs. Generally, this is done before the TI-RTOS Kernel is started.Void Driver_Params_init(Driver_Params *params)
— Initializes the driver’s parameter structure to default values. All drivers, with the exception of GPIO, implement the Params structure. The Params structure is empty for some drivers.Driver_Handle Driver_open(UInt index, Driver_Params *params)
— Opens the driver instance specified by the index with the params provided. If the params field is NULL, the driver uses default values. This function returns a handle that will be used by other driver APIs and should be saved. If there is an error opening the driver or the driver has already been opened, Driver_open() returns NULL.Void Driver_close(Driver_Handle handle)
— Closes the driver instance that was opened, specified by the driver handle returned during open. This function closes the driver immediately, without checking to see if the driver is currently in use. It is up to the application to determine when to call Driver_close() and to ensure it doesn’t disrupt on-going driver activity.
Drivers Porting Layer (DPL)
The Drivers Porting Layer allows the TI drivers to work with either the TI-RTOS or FreeRTOS kernel.
The TI Drivers use DPL APIs provided by the TI-RTOS and FreeRTOS Kernels for clock, interrupt, mutex, semaphore, and other services. However, the DPL abstracts the RTOS kernel functionality used by the drivers so that the application is not dependent on the TI-RTOS Kernel and can instead make use of the FreeRTOS kernel.
Board Files
Unless you are using SysConfig, TI Driver examples contain a board-specific C file (and its companion header file). The filenames are board.c and board.h, where board is the name of the board. All the TI Driver examples for a specific board use the same board files. These files are considered part of the example application, and you can modify them as needed.
The board files perform board-specific configuration of the drivers provided by the SDK. For example, they typically configure the GPIO ports and pins and configure use of the board LEDs.
Rebuilding Drivers
You can rebuild TI Drivers and many other libraries in the SDK by following these steps:
- In the root directory of the SDK installation, edit the
imports.mak
file (with a file extension for your operating system). - Modify the directory paths as needed for XDC_INSTALL_DIR, SYSCONFIG_TOOL, and NODE_JS.
Remove the definitions for any compilers you do not want to use when rebuilding drivers and libraries. That is, to omit a compiler, keep the line defining the environment variable, but leave the definition blank. For example:
CCS_ARMCOMPILER ?= c:/ti/ccsv8/tools/compiler/ti-cgt-arm_18.12.0.LTS GCC_ARMCOMPILER ?= IAR_ARMCOMPILER ?=
- Go to the
<SDK_INSTALL_DIR>/source/ti/drivers
directory. Notice that this directory contains amakefile
. Run the following commands:
>c:\ti\xdctools_<version>\gmake clean >c:\ti\xdctools_<version>\gmake
To build most other libraries, simply run these gmake commands in the directory that contains the makefile
for that library.
SysConfig
The SysConfig tool makes it easy to configure components like TI Drivers and device-specific components (such as the networking stack, EasyLink, and WiFi). SysConfig is available if you are using CCS 8.2 and a SimpleLink MCU SDK v2.30 or later.
For this release, SysConfig is optional and is available as a preview. Future releases will expand the use of SysConfig. See the “System Configuration Basics” lab in SimpleLink Academy for installation steps that are currently required and step-by-step instructions for using SysConfig. (The SysConfig interface is still subject to change, so some of the images below may be out of date.)
You can choose to use SysConfig no matter what your choice is for the following:
- Device: Supported for a range of SimpleLink devices and boards.
- IDE: Supported for CCS Desktop, CCS Cloud, and as a standalone desktop tool (for example, for use with IAR Embedded Workbench).
- Compiler Toolchain: Supported for the TI, IAR, and GCC toolchains.
- RTOS: Supported for TI-RTOS, FreeRTOS, and NoRTOS.
SysConfig versions of the examples are provided in the examples/sysconfig_preview
directory tree. These examples are basically the same as the examples in examples/rtos
and examples/nortos
, except they use SysConfig to generate configuration code instead of having the application provide it.
This section focuses on configuring TI Drivers, since all devices support TI Drivers using a common configuration framework. For TI Drivers, the SysConfig tool generates source files-–Board.c
and Board.h
-–to be compiled and linked with the application during builds. Additional components, such as networking stacks, may be configurable using SysConfig for certain targets, and will cause additional source files to be generated. See the device-specific documentation for information about any additional components that SysConfig can be used to configure.
SysConfig provides easy access to reference documentation for the drivers and other modules you can configure.
Besides the ease-of-use provided by SysConfig, the tool resolves conflicts on the fly. This ensures that you create a valid pin and TI Driver configuration. In addition, you can view diagrams of the pin configuration as you make changes.
SysConfig settings are stored in a file called <project>.syscfg
. Its output files are stored in a syscfg
folder within the build folder. For example, a “uartecho” application in CCS that uses TI-RTOS would contain the following files when built.
You open the <project>.syscfg
file in SysConfig and modify it as needed. You can view the Board.c
and Board.h
file contents within SysConfig and see how configuration changes affect the generated code.
When you save the uartecho.syscfg
file and build the project, the following actions occur:
- The
Board.c
andBoard.h
files are generated from the<project>.syscfg
file. - The
Board.c
andBoard.h
files are compiled to create aBoard.obj
file. - The
Board.obj
file is linked with the rest of the libraries to create the application.
Note that the XGCONF tool is separately used to configure TI-RTOS Kernel modules. The TI-RTOS configuration is stored in a *.cfg
file, which may be in a separate “kernel project” or in the same “application project” that contains the *.syscfg
file. Likewise, the FreeRTOS configuration file (FreeRTOSConfig.h
) is separately used to configure FreeRTOS.
Some users may choose to use SysConfig initially to generate the Board.c
and Board.h
files and then exclude the *.syscfg
file from the build so that manual changes made to the Board.c
and Board.h
files are not overwritten. In this case, you should manually move the generated Board.c
and Board.h
files from the build folder to the folder that contains your application source files, so that the board files will not be deleted when a clean build is performed.
Debugging Output
The Display middle-ware driver is the recommended strategy for providing “printf” style debugging. It is RTOS independent. The Display module supports sending debug output by different methods (for example, UART, IDE Console, and LCD). Application writers can also provide their own custom Display implementation.
Many of the TI Driver examples use the Display module to send debugging information out a UART or LCD. The main API is the Display_printf() functions. This function is very similar to the standard printf() function. The configuration for the Display module is in the board.c file. For details about the Display module functionality, refer to the reference documentation .
The Runtime Object View (ROV) tool is available for examining the runtime state of TI-RTOS Kernel objects and various important statistics, such as stack usage and CPU load. The ROV tool can be run standalone or within CCS 7.1 or later. For details on using the ROV tool, see the “Runtime Object View (ROV)” wiki topic.
Note: The default printf() API is not recommended for use with SDK applications due to the impact on real-time performance and code footprint size.
Note: The System module in the TI-RTOS Kernel is available for applications that use the TI-RTOS native APIs (instead of the POSIX APIs). The System module functionality is unchanged from previous versions and will continue to be supported. The TI-RTOS “release” configuration uses SysCallback as the System support proxy to minimize footprint and performance impacts. The TI-RTOS “debug” configuration uses SysMin as the System support proxy, which slightly impacts footprint and performance but allows viewing of the System_printf debug output in the RTOS Object Viewer (ROV). Refer to the Configuration with TI-RTOS section for more details about the release and debug versions.
TI-RTOS Kernel
The SDK includes the TI-RTOS Kernel.
TI-RTOS provides a rich set of system-level embedded software, including multi-tasking, power management, device drivers, and instrumentation. TI-RTOS includes support for the TI-RTOS Kernel and FreeRTOS. Through the use of industry-standard POSIX pthread APIs, TI-RTOS enables other kernels (schedulers) to be integrated. TI-RTOS is delivered in the SDK in a consistent manner across the various SimpleLink SDKs.
The TI-RTOS Kernel is a scalable real-time kernel. The kernel is designed to be used by applications that require real-time scheduling and synchronization or real-time instrumentation. It provides preemptive multi-threading, hardware abstraction, real-time analysis, and configuration tools. The Kernel is designed to minimize memory and CPU requirements on the target. This kernel was previously called SYS/BIOS.
The TI-RTOS Kernel is described in the TI-RTOS Kernel User’s Guide. Additionally, detailed reference information is provided for all the TI-RTOS Kernel APIs. The Texas Instruments Wiki links to training videos and more for the TI-RTOS Kernel.
Organization of TI-RTOS Kernel Modules
The TI-RTOS Kernel and the XDCtools underlying tooling it uses are organized into sets of “packages,” each of which delivers a subset of the product’s functionality. The package names reflect the physical layout of the package within the SDK installation. For example, the ti.sysbios.knl package files can be found in the <SDK_INSTALL_DIR>/kernel/tirtos/packages/ti/sysbios/knl
directory.
Each package provides one or more modules. Each module, in turn, provides APIs for working with that module. APIs have function names of the form Module_actionDescription(). For example, Task_setPri() sets the priority of a Task thread.
Using TI-RTOS Kernel Modules
In order to use a module, your application must include the standard TI-RTOS Kernel header files and the header file for that particular module. For example, include these header files to enable use of the Task module APIs:
#include <xdc/std.h> /* initializes XDCtools */
#include <ti/sysbios/BIOS.h> /* initializes TI-RTOS Kernel */
#include <ti/sysbios/knl/Task.h> /* initializes Task module */
Configuration with TI-RTOS
All TI-RTOS applications need a TI-RTOS configuration file (.cfg file). This file specifies how the kernel will be built. There are two methods for including the configuration in the application.
- Part of the same project: The .cfg file can be part of the application project. When the application is built, the .cfg file is also “built” and the generated files (source and linker file) are included in the application automatically. This method allows for fine tuning of the kernel for a specific application. Examples that use this method are in the
examples\rtos\<board>\sysbios
directory. - Part of a separate shared project: The application can point to a “shared” configuration project. The SDK provides the following two configurations in the
kernel\tirtos\builds\<board>
directory:- release: A non-instrumented version of the TI-RTOS kernel. The main features are present in this version of the kernel–for example, Tasking, Mailboxes, Semaphores, and Clock. This version has a small footprint and better performance than the debug version. This version is not the absolute minimum footprint because your application may not use all the RTOS kernel features.
- debug: An instrumented version of the kernel. This version enables asserts, logging, enhanced exception handling, and more. This version has the same RTOS feature set as the release version. This version is intended to be used during development. The separate configuration project method allows a configuration to be used by multiple applications. The build time for the application is faster, since it does not need to rebuild the kernel. The examples in the
examples\rtos\<board>
directory tree use this method.
Note: We recommend that you do not change the release.cfg and debug.cfg files. Instead refer to the following section if you want to create a new configuration.
For CCS users, when you import an example that uses Method 2, the separate configuration project specified by the example is also automatically imported.
Changing the TI-RTOS Configuration
The steps are different depending on whether the .cfg file is stored within your application project or in a separate project referenced by your application project.
Application Project Contains the .cfg File
You can simply edit the configuration file (via a text editor or the xGCONF tool in CCS). When the application is built, the kernel will be rebuilt also. This method applies for CCS, IAR and command line builds.
Application Project Does Not Contain the .cfg File
The steps are different depending on whether you are using CCS or IAR.
CCS Project
CCS projects can point to a separate configuration project in the Project Properties dialog in the Build->Dependencies tab.
Note: Don’t confuse the “RTOS configuration” with the “CCS Build Configuration”. The RTOS configuration does not need to correspond to the CCS Build Configuration (often also called Debug or Release).
By default, all TI driver examples use the “release” TI-RTOS configuration for both CCS Build Configurations.
To select a different configuration, import the desired configuration into CCS. To do this, follow these steps:
- Choose Project->Import CCS Project from the CCS menus.
- Next to Select search-directory, click Browse.
- Navigate to
<SDK_INSTALL_DIR>\kernel\tirtos\builds\<board>
directory and then eitherdebug
orrelease
. Then click OK. Check the box for the development environment you will use to build your application (CCS or GCC), and click Finish.