
.. _cc2640r2-cc23xx-migration-guide:

CC2640R2 to CC23xx Porting Guide
********************************

This section will describe, in general terms, how to port
a project developed for the CC2640R2 device on the 
|SDKF1| to a |DEVICE| device running 
the |SDK|.

The |SDKF1| offers examples using the BLE5 
stack and the BLE stack. The |SDK| implements the BLE5 stack,
so any projects running on the BLE stack on the |SDKF1|
must be migrated to the BLE5 stack before the porting process
begin. The migration process is detailed in the :ref:`blestack_to_ble5stack` guide.
Once the project is running on the BLE5 stack, then the best 
way to port a project is to open a new example project 
with similar functionality in the new SDK and transfer 
your changes and application code over to the new example.

The following sections discuss the major changes between the
CC2640R2 and the |DEVICE| devices.

* :ref:`sec-general-considerations-cc2640r2-to-cc23xx`

   * :ref:`sec-general-considerations-freertos-cc2640r2-to-cc23xx`

   * :ref:`sec-general-considerations-launchpad-support-cc2640r2-to-cc23xx`
   
   * :ref:`sec-general-sensor-controller-cc2640r2-to-cc23xx`

   * :ref:`sec-general-ble5-enabled-cc2640r2-to-cc23xx`

* :ref:`sec-migration-guides-cc2640r2-to-cc23xx`

   * :ref:`sec-migration-guides-ble5stack-cc2640r2-to-cc23xx`

   * :ref:`sec-migration-guides-freertos-cc2640r2-to-cc23xx`

   * :ref:`sec-migration-guides-ti-drivers-cc2640r2-to-cc23xx`

* :ref:`sec-compatibility-notes-cc2640r2-to-cc23xx`

* :ref:`sec-example-cc2640r2-to-cc23xx`

   * :ref:`sec-example-simple-peripheral-port-cc2640r2-to-cc23xx`

* :ref:`watchdog-example-code`

.. _sec-general-considerations-cc2640r2-to-cc23xx:

General Considerations
======================

.. _sec-general-considerations-freertos-cc2640r2-to-cc23xx:

FreeRTOS
--------
The |DEVICE| devices exclusively support FreeRTOS. If a project
needs to be migrated from the |SDKF1|, then
it will need to be converted to FreeRTOS during the migration process.

.. _sec-general-considerations-launchpad-support-cc2640r2-to-cc23xx:

LaunchPad support
-----------------

Find support and all the collaterals for the LaunchPad CC2340R5 in the
CC23xx LaunchPad Development Kit Product Page: `CC2340R5 LaunchPad`_.

.. _sec-general-sensor-controller-cc2640r2-to-cc23xx:

Sensor Controller
-----------------
The |DEVICE| does not support the Sensor Controller. Any applications being ported
from the |SDKF1| that make use of the Sensor Controller will
need to be modified to not use the Sensor Controller in order to work with the |DEVICE|.

.. _sec-general-ble5-enabled-cc2640r2-to-cc23xx:

Bluetooth 5.2 Enabled
---------------------

If your project wasn't already on a BLE5 platform, the |DEVICE| will provide the
ability to support the new features of Bluetooth 5.2. This includes features such
as higher throughput, longer range, advertising extensions, and improved coexistence
with other wireless technology.

.. _sec-migration-guides-cc2640r2-to-cc23xx:

Migration Guides
================

.. _sec-migration-guides-ble5stack-cc2640r2-to-cc23xx:

Migrate to BLE5 stack
---------------------

If migrating from a |SDKF1| based project to a
|SDK| based project, then it is necessary to migrate the |SDKF1|
project to the BLE5 stack if its not already in the BLE5 stack. This initial migration
will greatly ease the porting process further down the line.

If the project has not already been migrated to the BLE5 stack, then the :ref:`blestack_to_ble5stack`
guide should be leveraged to aid in this section of the migration.

.. _sec-migration-guides-freertos-cc2640r2-to-cc23xx:

Migrate to FreeRTOS
-------------------

An important step that must be taken in order to port an example from the
|SDKF1| to the |SDK| is to ensure that
the project is implemented in FreeRTOS. The |SDK| only supports
FreeRTOS, so any projects running on TI-RTOS will not work unless they
are converted to FreeRTOS. To port a project from TI-RTOS to FreeRTOS
please reference :ref:`sec_freertos_migration_cc23xx_application`. This part
of the process should be done after the application code has been transferred
to a sample project running on the |SDK|.

.. _sec-migration-guides-ti-drivers-cc2640r2-to-cc23xx:

Migrate the TI drivers
----------------------

It is important to ensure that projects that are being ported to CC23xx are
not using deprecated libraries. A few migration guides for libraries
that should be updated as part of the |SDKF1|
to |SDK| migration are shown below:

*  :ref:`uart_to_uart2-porting-guide`
*  :ref:`sec-cc23xx-gpio++-porting-guide`

.. _sec-compatibility-notes-cc2640r2-to-cc23xx:

Compatibility Notes
===================

Due to a number of improvements and feature additions, the recommended migration
path for customers is to start with a CC23xx based project and migrate any
custom application code and project configuration to the new project.

The following sections describe, in general terms, the software differences when
migrating from CC2640R2 to CC23xx.

.. include:: inc_cc2640r2_compatibility-cc23xx.rst

.. _sec-example-cc2640r2-to-cc23xx:

Example
=======

The following section provides an example of how to port a BLE5 
CC2640R2 project from the |SDKF1| to the |SDK|. 
All of the steps shown below are essentially putting into practice the
theory discussed earlier in this document.

.. _sec-example-simple-peripheral-port-cc2640r2-to-cc23xx:

Porting Simple Peripheral
-------------------------

For this porting guide, BLE5 Simple Peripheral will be ported from the 
|SDKF1| device to the |SDK| using a |DEVICE_LOW_PLUS|
device. To minimize project configuration differences, start with an 
example project in the |DEVICE|. The recommended approach is to start
with a |SDK| project that contains the same base functionality as the 
porting target project and merge in any custom functionality. 

Examples based on the Simple Framework (`simple_peripheral`, `simple_central` etc.) can be
migrated to the `basic BLE` example. This section will detail how to migrate from
`simple_peripheral` to `basic_ble`.

.. hint::
   Note that the `basic_ble` project from the |SDK| gather all the following project from the |SDKF1| in one:

   * `simple_peripheral`

   * `simple_central`

   * `simple_obsverer`

   * `simple_broadcaster`

   When using the basic_ble example, SysConfig should be used to enable the required Bluetooth role(s).

#. Choose a |SDK| example project that contains your target
   project's base functionality, it's better to choose the `basic_ble` project 
   as it handle all the different roles.

   Build the newly created project to avoid any errors related to the build environnement.

#. Transfer SysConfig settings
On the |SDK| a file called sysconfig gather a lot of configuration through a GUI.

For example all the files concerning the board itself should be implemented in sysconfig.
There is no ``board.c`` file in `basic_ble` project.

Select the desired Bluetooth LE role(s) role. In the case of `simple_peripheral`, select "Peripheral"

Select desired BLE parameters.

Add any necessary SysConfig modules (UART, SPI, I2C, etc.)

Remove any unneeded SysConfig modules.

#. Transfer Bluetooth LE profiles from the `simple_peripheral`` project to the `basic_ble` project.

   In the `simple_peripheral` project, the profiles may be found at the 
   following directory: `{PROJECT_LOC}/Profiles`

   In the `basic_ble`` project, the profiles may be found at the 
   following directory: `{PROJECT_LOC}/common/Profiles` 

   Make sure that any **#include** statements that reference the `simple_peripheral`
   directory structure are updated to use the `basic_ble` directory structure if needed.

#. Update the project to use the newer TI drivers that are
   supplied with the |SDK|.

   The UART library has been deprecated and replaced by the UART2 library.
   Please follow the  :ref:`uart_to_uart2-porting-guide`

   The Pin and GPIO libraries are deprecated and have been replaced by the
   GPIO++ library. To update Pin or GPIO code, please reference the following
   porting guide :ref:`sec-cc23xx-gpio++-porting-guide`


#. Convert the project from TI-RTOS to FreeRTOS. The |Device| devices only support FreeRTOS.
   This must be done properly to ensure that the project behaves as expected and 
   proper functionality is maintained. Please leverage the following guide 
   :ref:`sec_freertos_migration_cc23xx_application`
 

#. Remove any unnecessary application files within the ``app`` folder

   * For example, if your application will only implement the observer role, then the ``app_broadcaster.c``,
     ``app_central``, ``app_data``, ``app_pairing``, and ``app_peripheral`` may be removed.
     These additional files implement functionality that may not be useful in an observer-only application.

   * In the case of the `simple_peripheral` example, only the ``app_broadcaster.c``, ``app_central``,
     and ``app_observer`` should be removed if only the ``simple_peripheral`` functionality is desired.


#. Transfer custom application code to the `basic_BLE` project.

   * Almost all of the application code present in the `simple_peripheral` project was located in
     the ``simple_peripheral.c`` file. In the `basic_ble` project, a lot of potentially unnecessary
     code is removed entirely and the remaining code is placed in modular files that can be expanded 
     or minimized as needed.

   * The functionality of the custom code as well as the location of the custom code in the
     `simple_peripheral` project will determine the best location in the `basic_ble` project
     to transfer the code to.
   
     For example, any custom code added to the pairing process should likely be added to ``app_pairing.c``
     file.
      
     Any custom code that deals with peripheral specific functionality such as advertising or connecting 
     should likely be added to the ``app_peripheral.c`` file.
      
     Any code that is not directly related to the BLE5Stack operation can be placed in its own file
     within the app or common folders.

   * Highly customized code may require a bit more effort to migrate, but should be relatively
     straight forward to do so.

#. Refer to the Core SDK release notes for additional information and the 
   FreeRTOS examples included with |SDK|.

   For additional information on how |SDK| uses FreeRTOS see
   :ref:`sec-freertos-overview`.

#. At this stage, most, if not all, of the modifications required have been completed.
   It is possible that some additional modifications may be required for the project
   to function as intended, but these changes can be relatively minor compared to the
   modifications already made by following this porting guide.