CC253x to CC13x2 or CC26x2

Introduction

This section describes the main differences an application developer must be aware of between CC253x and CC13x2 or CC26x2 devices along with a porting guide to demonstrate the migration effort.

Features and Benefits

Increased Processing Power and Scalability

The CC13x2 or CC26x2 is a wireless MCU with a dedicated Arm Cortex-M4F application processor. More memory is available with an increase of non-volatile memory to 608kB. This breaks down into 352kB Flash memory + 256 KB ROM. RAM has also increased to 80 kB. The availability of this increased memory provides support for Over-the-Air Downloads (OAD), larger applications, and more simultaneous connections. An additional UART is also included.

Lower Power Operation and Zigbee Green Power Devices

A 50% reduction in standby current and 70% reduction in current consumption through the Sensor Controller allows for long-term operation from a single AA or coin-cell battery for sleepy end devices. If an end application project requires battery-less products, the CC13x2 or CC26x2 will provide the ability to support both Green Power Source and Sink Devices.

Enhanced Security

With additional hardware security accelerators for AES-128/256, SHA-256, and ECC, CC13x2 or CC26x2 saves five times the processing time and current consumption for implementing security algorithms. This is critical to enable strong network security.

CC13x2 and CC26x2 LaunchPad Support

All example applications are compatible with the CC13x2 or CC26x2 LaunchPad development kit. These features allow for a unified development experience and empowers developers to rapidly release to market.

• CC26X2R1 LaunchPad Development Kit Product Page
• CC2652RB LaunchPad Development Kit Product Page
• CC1352P LaunchPad Development Kit Product Page
• CC1352R1 LaunchPad Development Kit Product Page
• CC1352R1 LaunchPad SensorTag Kit Product Page

TI-RTOS Adoption

TI-RTOS is the new operating environment for Zigbee projects on CC26xx devices. This software is a multi-threaded environment where the protocol stack, application, and its profiles exist on different threads. TI-RTOS has similar features to OSAL but different mechanisms for accomplishing them. This section covers the main differences between TI-RTOS and OSAL when developing applications on top of the Zigbee protocol stack. Although the incorporation of TI-RTOS is a major architecture change, Zigbee APIs and related procedures are similar to CC253x.

This section covers the following topics:

• OSAL removal
• Application and stack separation with ICall/OSALPort
• Threads, semaphores, and queues
• Peripheral Drivers
• Event Processing

Most of these differences are unique to TI-RTOS. This section covers these differences and how they relate to OSAL.

Note

ICall has been replaced with OSALPort since Z-Stack 3.3.0, please refer to Z-Stack 3.2.0 to Z-Stack 3.3.0 for more information

OSAL Removal

A major change in moving to TI-RTOS is the complete removal of the application from the OSAL environment. While the stack code uses OSAL within its own thread, the application thread can only use the APIs of OSAL that are defined in icall.h/osal_port.h. Many functions such as osal_memcpy, osal_memcmp, and osal_mem_alloc() are unavailable. These functions have been replaced by TI-RTOS, C runtime, and Z-Stack APIs.

Application and Stack Separation With ICall/OSALPort

In the Zigbee protocol stack, the application is a separate image from the stack image unlike the OSAL method, which consists of only a single image. This structure allows independent upgrading of the application and stack images.

The address of the startup entry for the stack image is known by the application image at build time so the application image knows where the stack image starts. Messages between the application and stack pass through a framework developed called ICall/OSALPort. This functionality lets the application call the same APIs used in OSAL but is parsed by the ICall/OSALPort and sent to the stack for processing. Many of these stack functions are defined in zstackapi.c for the application to use transparently while ICall/OSALPort handles the sending and receiving from the stack.

Threads, Semaphores, and Queues

Unlike single-threaded operating systems such as OSAL, TI-RTOS is multi-threaded with custom priorities for each thread. The TI-RTOS handles thread synchronization and APIs are provided for the application threads to use to maintain synchronization between different threads. Semaphores are the prime source of synchronization for applications. The semaphores are used to pass event messages to the event processor of the application.

Profile callbacks that run in the context of the Zigbee protocol stack thread are made re-entrant by storing event data and posting a semaphore of the application to process in the context of the application. Similarly, key press events and clock events that run in ISR context also post semaphores to pass events to the application. Unique to TI-RTOS, queues are how applications process events in the order the events were called and make callback functions from profiles and the stack re-entrant. The queues also provide a FIFO ordering for event processing. An example project may use a queue to manage internal events from hardware (key or UI), device type (coordinator, router, or end device), or cluster (for example, level control or temperature measurement) event. ICall/OSALPort uses a queue and it is accessed through the respective API. For a description of the TI-RTOS objects used by the Z-Stack SDK, see TI-RTOS (RTOS Kernel) Overview.

Peripheral Drivers

Aside from switching to an RTOS-based environment, peripheral drivers represent a significant change from the CC253x architecture. Any drivers used by the CC253x software must be ported to the respective TI-RTOS driver interfaces. For details on adding and using a CC26xx peripheral driver, see Configure The Board Files with SysConfig.

Event Processing

Similar to OSAL, each TI-RTOS task has two functions that implement the fundamental tasks for an application: [project name]_initialization() and [project name]_process_loop().

[project name]_initialization() contains ICall/OSALPort registration routines. The initialization includes setting up callbacks that the application should receive from the profile and stack layers. For more details on callbacks, and other messaging systems see Callbacks.

[project name]_process_loop() contains an infinite loop in which events are processed. After entry of the loop and having just finished initialization, the application task calls ICall_wait() or Semaphore_pend() to block on its semaphore until an event occurs. Reference the Zigbee stack sample applications for a detailed example.

Similar to osal_set_event() in a CC253x application, the application task can post the semaphore of the application with a call to Semaphore_post(sem) after setting an event such as in [project name]_changeKeyCallback(). Similar to osal_start_timerEx() in a CC253x application, clocks can be used to set an event after a predetermined amount of time using Timer_construct. This function can also set a periodic event as shown in the zed_samplethermostat project.

Events can come from within the same task, the profiles, or the stack. Events from the stack are handled first with a call to ICall_fetchServiceMsg() or OsalPort_msgReceive(), similar to osal_msg_receive() in a CC253x application. Hardware events and messages from Zigbee clusters, that are received in endpoint callback functions, must be treated as re-entrant and should be handled in the [project name]_process_loop() function too. In other words, processing should be done within the application context. In many cases such as with endpoint cluster callbacks, events must be placed in a queue to preserve the order in which messages arrive. For general overview of application architecture see Application Architecture.

Porting Instructions from Z-Stack 1.2.2a/3.0.x to 3.1.0

The intention of these instructions is to help developers convert thier legacy Zigbee projects to the SimpleLink CC13x2 / 26x2 SDK. This includes collecting all of the essential materials from the legacy Z-Stack project and recognizing the mesh network settings to which the new project must adhere. It will then require importing a SimpleLink CC13x2 / 26x2 SDK sample application, renaming all appropriate resources, changing mesh network configurations, and customizing the application files.

Note

This module is intended to provide a process overview and does not go into specific detail about each conversion aspect that should be considered per application.

1. Copy the project files. All significant application resources should be contained inside of the C:\Texas Instruments\Z-Stack Home 1.2.2a.44539\Project\zstack\HomeAutomation\<Zigbee Project>\Source folder of the IAR project. For basic designs this will consist of three files: zcl_[application].c, zcl_[application].h, and zcl_[application]_data.c. All files should be copied to a location on the system that can be accessed for later review. The only exception is OSAL_[application].c which is not relevant to the TI-RTOS-based SimpleLink SDK.

2. Examine all configuration settings. Zigbee projects contain several options that determine how the mesh network operates. To duplicate this behavior inside the new project one must take note of the most important settings so that they may be reformatted inside the SimpleLink Zigbee SDK. The description of the most crucial variables are captured in Network Configurations and located in the following IAR workspace locations:
   • NWK\nwk_globals.h
   • NWK\ZGlobals.h
   • Tools\f8wConfig.cfg
   • Project Options → C/C++ Compiler → Preprocessor → Defined symbols

Some variables have been added to Z-Stack 3.0, hence these files should not be copied directly from a Z-Stack HA 1.2.2a project.

Note

Z-Stack HA 1.2.2a is based off of the Zigbee PRO 2012 (r20) specification whereas Z-Stack 3.x.x follows Zigbee PRO 2015 (r21) and later. There are several significant changes between these specifications that greatly affect the behavior of the Zigbee mesh network, including child aging, enhanced security, BDB specification, and Green Power as described in the What’s New in Zigbee 3.0 White Paper. Caution should be taken to recognize these differences and the new/altered mesh network settings thereof.

3. Import a SimpleLink CC13x2 / 26x2 SDK project into Code Composer Studio (CCS) or IAR. CCS will be used for demonstrative purposes, use either of the following options inside the IDE:

   • View → Resource Explorer → SimpleLink CC13x2 / 26x2 SDK → Connectivity → Examples → Development Tools → CC13x2 or CC26x2 LaunchPad
   • File → Import → C/C++ Project → CCS Project, search directory C:\ti\simplelink_cc13x2_26x2_sdk_x_xx_xx_xx\examples\rtos\CC13x2 or CC26x2_LAUNCHXL\zstack

Import either the genericapp example or a sample application that reflects the desired application, such as switch for a light switch device. The corresponding Zigbee node type project must also be selected: coordinator (ZC), router (ZR), or end device (ZED). Make sure to build the project (Project → Build Project) before continuing and verify that all file paths resolve correctly as this will confirm the starting point for further code modifications.

4. Alter project names so that all application-specific files and dependencies now match the intended end application. Inside the Project Explorer, right-click on the Project and choose Rename (or F2) to perform this task. The same should be done for all Application files. Furthermore, it is good practice to replace the format of all functions, defines, etc. that use the old naming convention. Go to Edit → Find/Replace (or Ctrl+F), create the search parameters, and perform a Replace All for each application file.

A new Project Configuration name should be chosen (Project Properties → CCS General → Manage Configurations) and an entire project search (Search → File Search with Scope of Enclosing projects) will help verify that there are no old identities remaining. At this point, it is advised that the project be cleaned (Project → Clean Project) and re-built to confirm that nothing has broken while changing names. The original configuration build folder can now be deleted after the new one is generated.

Note

Case sensitivity should be taken into account for each Find/Replace Search and it is recommended to try multiple instances to make sure everything has been correctly revised. The only name change required outside of the application files is in Application\StartUp\main.c where zcl[Project]_task should be renamed and the header include should be changed to Application/zcl_[Project].h

5. Apply changes to the mesh network configuration files. The Network Configurations section will further help complete this task. The most common variable locations inside the CCS workspace are as such:

   • Application\Stack\nwk\nwk_globals.h
   • Application\Stack\sys\zglobals.h
   • Application\Stack\Config\f8wconfig.opts
   • Application\Stack\bdb\bdb_interface.h
   • Project Properties → CCS Build → ARM Compiler → Predefined Symbols

   A list of valid Predefined Symbols is provided in Application Preprocessor Configuration.

The preprocessor symbols in the SimpleLink CC13x2 / 26x2 SDK are different to those from the OSAL projects, however the most important ones to notice are documented in Application Preprocessor Configuration. The project Stack and Heap can also be altered in TI_RTOS_Configuration\app.cfg alongside other TI-RTOS settings.

6. Make changes to the project files(zcl_[application].c, zcl_[application].h, and zcl_[application]_data.c) to support the application. This will include:
   • Considering OSAL to TI-RTOS changes as highlighted in TI-RTOS Adoption
   • Modifying initialization including endpoint, attribute, and cluster registration
   • Changing Z-Stack and AF message handling
   • Adding UI callback functions
   • Updating cluster callback functions

Each of these points are detailed further in the Z-Stack 1.2.2a (CC253x) to Z-Stack 3.1.0 and Z-Stack 3.0.x to Z-Stack 3.1.0 porting guides. It is also recommended that difference comparison software be used to further understand the variation between the old and new Z-Stack project files.

7. Build the project and address each issue that spawned due to the migration. Once no errors remain, the project itself will need to be further debugged to ensure that the application operates as expected.

Note

Additional steps or changes will be required to further port the project to a Z-Stack version newer than 3.1.0. Please see the respective Porting Guides for further details.