Application Development¶

The SimpleLink CC13xx/CC26xx SDK for TI-OpenThread is intended to be developed with one of the following development boards:

The SDK provides the source code of the OpenThread stack, found in the source/third_party/openthread/ folder under the SDK installation directory. The SDK does not provide any pre-compiled libraries for OpenThread.

IDEs and Toolchains¶

All TI-OpenThread examples can be built with the following IDEs and toolchains:

Code Composer Studio, built with TI-CLANG
Code Composer Studio, built with GCC
IAR Embedded Workbench

When importing TI-OpenThread examples in Code Composer Studio (CCS) there are two variants for each example: one for the TI-CLANG Compiler with the ticlang suffix, and one for the GCC toolchain with the gcc suffix.

Build and Run Examples¶

Building TI-OpenThread examples in TI-CLANG is as simple as importing the example into the IDE and start building. Either navigate in Resource Explorer to the example in question and import as usual, or manually import the example from the installed SDK.

When the example is imported, you will see multiple projects are imported in addition to the example project. These are the OpenThread and mbed TLS libraries which are compiled alongside with the example.

To start building, right click the example project in the Project Explorer view and click Build Project. The first build will take some time compared to subsequent builds, as the TI-RTOS7 Kernel, the OpenThread stack, and the mbed TLS are compiled for the first time.

When the build finishes, start a debug session by clicking the Debug symbol or Run → Debug. The device is programmed with the compiled example application and the debug session halts at main().

OpenThread API Mutex¶

As described in Application Architecture, an API mutex is employed by TI-OpenThread when accessing the OpenThread API. This was to ensure coherent access to the OpenThread APIs by both the user application tasks and the OpenThread stack task.

The API mutex is available in the OtRtosApi module, found under the otsupport/ folder in the example project. The OtRtosApi module is initialized by the OpenThread stack task.

The underlying implementation of the API mutex uses pthread_mutex_t. For more information, see TI-POSIX User’s Guide.

Usage of the OtRtosApi module is straightforward: any task that wants to access the OpenThread API must first lock the mutex, access one or more OpenThread APIs, and finally unlock the mutex.

Listing 18. OpenThread API mutex usage.¶

#include <otsupport/otrtosapi.h>

void foo(void)
{
    OtRtosApi_lock();
    /* Access one or more OpenThread APIs */
    OtRtosApi_unlock();
}

Warning

Be aware that if a task fails to unlock the API mutex after locking it, any other tasks trying to access the API mutex will result in a deadlock. In other words, tasks trying to lock the API mutex will never return.

OpenThread Configuration¶

Note

Application-level configuration with SysConfig is supported for TI-OpenThread. See Section TI-OpenThread SysConfig for more information.

The OpenThread stack comes pre-configured with TI-OpenThread, with default settings provided for the following device configurations:

MTD – configuration files located in library libopenthread_mtd_<platform>
FTD – configuration files located in library libopenthread_ftd_<platform>
NCP – configuration files located in library libopenthread_ncp_<platform>

<platform> denotes in this context the device family and the toolchain. E.g. a MTD for CC26x2R LaunchPad on CCS would have the name libopenthread_mtd_cc13x2_26x2_ticlang.

Attention

Be aware that these device configuration libraries are shared among projects with the same device configuration. Therefore, a change in the OpenThread configuration in one of the libraries will affect all other projects with the same device configuration.

TI recommends to keep separate CCS workspaces for multiple configurations of the OpenThread stack.

OpenThread is configured by a set of various compile-time configuration constants in the form of preprocessor macro defines. These macro defines can be overridden or changed for different functionality and behavior. Configuration consists of a core configuration and a device configuration. The core configuration is used by the OpenThread stack, while the device configuration is used by the project and the TI-OpenThread platform.

The device configuration is used to enable and disable functionalities of the OpenThread stack, such as CoAP, DHCPv6, and more. For an exhaustive list, consult the device configuration file. Enable or disable each functionality by directly modifying the device configuration file.

Available configuration options are detailed at the following locations in the imported device configuration library:

Core configuration – found under src/core/openthread-core-default-config.h
Device configuration – found under config/openthread-config-<platform>.h

<platform> denotes in this context the device family, toolchain and device configuration. E.g. the configuration file for a MTD for CC2652 on CCS is config/openthread-config-cc13x2_26x2-ccs-mtd.h.

Low-Power Operation¶

Thread provides support for low-power devices by defining a device type called Sleepy End Device (SED). A SED is a MTD which has the ability to disable the transceiver when idle, which allows for battery-constrained devices to operate in a Thread network.

By default in OpenThread, a MTD is configured as a MED. In order to configure a MTD to be a SED the rx-on-when-idle value in the Thread device mode must be unset. Additionally, the data poll period can be configured, but is not required.

The Thread device mode is configured in OpenThread as follows:

Listing 19. Sleepy End Device configuration in OpenThread.¶

#include <openthread/error.h>
#include <openthread/instance.h>
#include <openthread/link.h>
#include <openthread/thread.h>

void configureSleepyEndDevice(otInstance *aInstance, uint32_t aPollPeriod)
{
    otLinkModeConfig linkMode;
    otError error;

    /* Set Thread device mode for SED */
    linkMode.mRxOnWhenIdle       = 0;  /* Must be set to 0 for SED */
    linkMode.mSecureDataRequests = 1;  /* Must be set to 1 */
    linkMode.mDeviceType         = 0;  /* Must be set to 0 for MTD */
    linkMode.mNetworkData        = 1;  /* Can be either 0 or 1 */

    /* Update Thread device mode and data poll period.
     * Any appropriate error checking should be done.
     */
    error = otThreadSetLinkMode(aInstance, linkMode);
    otLinkSetPollPeriod(aInstance, aPollPeriod);
}

FCC Testing Functionality¶

FCC and other similar RF regulatory bodies often require certain certifications to be fulfilled before a product is brought to market, even though the Thread protocol makes no such requirements. Therefore, it is desirable to have FCC testing functionality available in a Thread example project.

The diag (diagnostic) module in OpenThread provides a set of commands to manipulate the radio from within the OpenThread environment. The diag module is accesible from the OpenThread CLI application.

Mainly two FCC testing functionalities are supported: PER test functionality with SmartRF Studio compatibility, and test of continuous tone. The result of a PER test is calculated in the same fashion as SmartRF Studio, shown in equation (1).

(1)¶ $\text{Error Count} &= \text{CRC Error Count} + \text{Lost Packet Count} \text{Packet Error Rate}[\%] &= \frac{\text{Error Count}}{\text{Packet Count} + \text{Error Count}} \times 100$

Test of Continuous Transmission¶

The API for starting and stopping a continuous transmission is on the following format:

diag transmit start <packet size> <interframe space> <transmit count>
diag transmit stop

Packet size specifies the payload of the packet in bytes, the interframe space specifies time beween each packet in milliseconds, and transmit count specifies the number of packets to send.

Note

If you want to receive and observe the transmitted packets, you can use an IEEE 802.15.4-capable LaunchPad with SmartRF Studio, configuring the device to the same channel in Packet RX mode expecting infinite packets. This is optional.

To start a test of continuous transmission with your Thread device, do the following:

Build and flash the cli_ftd example application.

Input the following commands in the UART CLI.

diag start
diag channel 12
diag power 5
diag transmit start 100 30 500

(Optional) Observe the packets in SmartRF Studio.
Stop the transmission with the commands in the UART CLI.
```
diag transmit stop
diag stop
```

After stopping the transmission, a test report is displayed with statistics over how many packets were transmitted.

For channels near the band edge (such as channel 25 and 26), it may be necessary to lower the maximum output power to pass FCC certification tests. As this is dependent on the hardware design, refer to the following code to set the appropriate power limit for your design.

/**
 * Array of back-off values necessary for passing FCC testing.
 */
static const struct tx_power_max cTxMaxPower[] =
{
    { .channel = 26, .maxPower = 15 }, /* back-off for 25 deg C, 3.3V */
    { .channel = 25, .maxPower = 19 }, /* back-off for 25 deg C, 3.3V */
};

Test of Continuous Reception¶

The API for starting and stopping a continuous transmission is one the following format:

diag receive start
diag receive stop

No additional parameters are required. Stopping the continuous reception will present a PER report of packets received.

Note

It is required to have a device sending out a continuous transmission on the same channel, while the continuous reception test is running to have any meaningful results. Either setup SmartRF Studio with an IEEE 802.15.4-capable LaunchPad in Packet TX mode on the same channel sending infinite packets, or see Test of Continuous Transmission.

To start a test of continuous reception with your Thread device, do the following:

Build and flash the cli_ftd example application.

Input the following cmmands in the UART CLI.

diag start
diag channel 12
diag receive start

Start packet transmissions from your other device.
When satisfied, stop packet transmissions.
Stop the transmission with the commands in the UART CLI, observing the report.
```
diag receive stop
diag stop
```

After stopping the reception, a test report is displayed with statistics over received packets, including PER.

Test of Continuous Tone¶

The API for starting and stopping a continuous tone is one the following format:

diag tone start
diag tone stop

No additional parameters are required. To observe the continuous tone, setup a Spectrum Analyzer near the DUT; or, setup SmartRF Studio in Continuous RX mode on the same channel.

To start a test of continuous tone with your Thread device, do the following:

Build and flash the cli_ftd example application.

Input the following cmmands in the UART CLI.

diag start
diag channel 12
diag power 5
diag tone start

Observe the transmission over the air with the Spectrum Analizer or SmartRF Studio.
Stop the transmission with the commands in the UART CLI, observing the report.
```
diag tone stop
diag stop
```

No test report is displayed after stopping the tone.