.. highlight:: text

.. _general_quickstart_cc23xx:

Introduction to the |SDK|
*************************

.. Commented out ADD THIS BACK WHEN CC23XX Device supports Zigbee and 15.4
    The |SDK| delivers components that enable engineers to develop applications on
    the Texas Instruments SimpleLink |DEVICE| family of wireless microcontroller
    (MCUs). This powerful software toolkit provides a cohesive and consistent
    software experience for all SimpleLink |DEVICE| wireless MCU users by packaging
    essential software components, such as a Bluetooth\ |reg| Low Energy (BLE)
    protocol stack supporting Bluetooth 5, TI’s 15.4 Stack, RF-Proprietary examples, 
    a Zigbee stack as well as the TI-RTOS kernel and TI Drivers in one easy-to-use 
    software package along with example applications and exhaustive documentation.

The |SDK| delivers components that enable engineers to develop applications on
the Texas Instruments SimpleLink |DEVICE| family of wireless microcontroller
(MCUs). This powerful software toolkit provides a cohesive and consistent
software experience for all SimpleLink |DEVICE| wireless MCU users by packaging
essential software components, such as a Bluetooth\ |reg| Low Energy (Bluetooth 
LE) protocol stack supporting Bluetooth 5 and RF-Proprietary examples, the Free-RTOS 
kernel and TIDrivers in one easy-to-use software package along with example 
applications and exhaustive documentation.

Prerequisites
=============

All you need to get started: 

* One |LP_CC23xx|
* A computer running a supported operating system listed in the Release Notes

.. tip::

    To get your first program running on the |DEVICE| the fastest route is to use CCS Cloud
    as it requires minimum installation and setup. When going further in the development,
    users generally prefer to install locally the tools they need - guidance through this
    process can also be found in this document.

Development using CCS Cloud 
===========================

The fastest way to get started is to use CCS Cloud. 
When using CCS Cloud, *everything* is in the cloud 
so you do not need a local installation of the 
compiler (TIClang), IDE or SDK. 

1. Visit `TI Developer Zone <https://dev.ti.com/>`_, and make sure you are
   signed in.

2. Click on `Create a new project`. 

3. Select your board, in this case lets use `CC2340R5 LaunchPad`. 

.. figure:: resources/ccs_cloud_board_select.png
    :align: center

4. Select the target example to use, lets use the `empty` project initially. 

.. figure:: resources/ccs_cloud_select_new_project.png
    :align: center

5. Set the compiler and kernel, lets use `TI Clang` and `FreeRTOS`. 

.. figure:: resources/ccs_cloud_configure.png
    :align: center

6. Click create. 

7. A new window will open with CCS Cloud, open the file explorer to view your
   projects, and select the `empty.c` file to edit as needed. 

.. figure:: resources/ccs_cloud_open_empty.png
    :align: center

.. tip::

    The sections here after guide you through the installation process
    and first steps with locally installed tools.

    You will be guided to install an IDE (CCS or IAR) and the SDK.

    Optionally, you can also install the `Flash Programmer (UniFlash) <#uniflash-for-device>`_
    and the `RF Evaluation tool (SmartRF Studio) <#smartrf-studio-for-device>`_.

IDE - Download and Installation
===============================

Only one IDE (CCS or IAR) is required.
For CCS, refer to :ref:`ccs-download-and-installation`.
For IAR, refer to :ref:`iar-download-and-installation`.

.. _ccs-download-and-installation:

CCS Download and Installation
-----------------------------

    This section covers the required settings for a CCS installation.
    The CCS toolchain contains many features beyond the scope of this document.
    More information and documentation can be found on the `Code Composer Studio`_ tool page.

    Check the |SDK| release notes to see which CCS version to use and any
    required workarounds. Object code produced by CCS may differ in size and
    performance as compared to IAR produced object code.

#.  Download and install `TI Arm Clang Compiler Tools`_. We recommend that you
    use the default installation folder.

#.  Download CCS

    CCS is available here: `Code Composer Studio`_ .

    Refer to the SDK release notes for the version that is compatible with
    this SDK.

#.  Installation Options

    During the installation, the following options are recommended:

    * We recommend that you use the default installation folder

    .. _fig_default_install_path:

    .. figure:: resources/ccs-install.png
        :align: center
        :width: 80%

        Default CCS Installation Location

    * You will then be prompted to select the components. 
      Select "Wireless connectivity". 

    .. _fig_processor_support_options:

    .. figure:: resources/ccs_install_select_processor_support.png
        :align: center
        :width: 80%

        Select Processor Support


    To use a debug probe, select TI XDS Debug Probe Support and any other options
    you would like. The |LP| uses TI XDS Debug Probe by default.

    .. _fig_ccs_debugger_options:

    .. figure:: resources/ccs-v11-debugger-options.png
        :align: center
        :width: 80%

        CCS Debugger Options

#.  Discovering the SDK in CCS

    If not already done, install the SDK in the default location pointed to by the installer -
    ``c:/ti`` and restart CCS. CCS will automatically detect the latest install.

    Code Composer Studio automatically discovers the |SDK| if it installed in its
    default installation directory (``c:/ti``). Once discovered by CCS, it defines a
    build environment variable named |CCS_INSTALL_VAR| which is used by all |SDK|
    projects.

    If a project is imported from a path other than what was specified
    during the |SDK| installation, the |CCS_INSTALL_VAR|
    variable must be redefined after the import proceeding at a project-by-project
    basis. Project import is described later in this guide.

    To redefine this variable:

    #. Open the CCS project's properties (**Project** |rarr| **Properties**)
    #. Navigate to **Resource** |rarr| **Linked Resources** and *edit*
       |CCS_INSTALL_VAR| and have it point to your
       imported root directory location.

       .. figure:: resources/cc2340rx/redefine-ccs-linked-resources-cc23xx.png
            :align: center
            :width: 75%

            Redefining |CCS_INSTALL_VAR|

.. tip::
    You are done with CCS installation and setup. You can now proceed with
    :ref:`sdk-download-and-installation`

.. _iar-download-and-installation:

IAR Download and Installation
-----------------------------

This section covers the required settings for a IAR installation.
The IAR toolchain contains many features beyond the scope of this document.
More information and documentation can be found at `IAR.com <https://www.iar.com>`_.

Not all components in the |SDK| support IAR projects. Check the |SDK| and
component release notes to check IAR support, which IAR version to use and any
required workarounds. Object code produced by IAR may differ in size and
performance as compared to CCS produced object code.

1. Download IAR

   Download and install IAR Embedded Workbench for Arm. Please see the SDK
   release notes for what version of IAR the SDK supports. You can get IAR for
   Arm here: https://www.iar.com/iar-embedded-workbench/partners/texas-instruments/ti-wireless/

    To get IAR, choose one of the following methods:

        - Download the IAR Embedded Workbench 30-Day Evaluation Edition –
          This version of IAR is free, has full functionality, and
          includes all of the standard features. The size-limited
          Kickstart evaluation option is not compatible with this SDK.

        - Purchase the full-featured version of IAR Embedded Workbench – For
          complete Bluetooth LE application development using the |DEVICE|, TI
          recommends purchasing the complete version of IAR without any
          restrictions. You can find the information on purchasing the complete
          version of `IAR <https://www.iar.com/buy>`_.

    .. attention::
        The version required is stated in the release notes.
        Opening IAR project files with a previous version of IAR may cause
        project file corruption.

2.  Installation Options

    Begin Installation by selecting Install IAR Embedded Workbench\ |reg| for
    Arm.

    .. _fig-iar-install:
    .. figure:: resources/iar-install.jpg
       :align: center

       IAR Installer

    Click through the installation confirm windows and license agreement. We
    recommend installing to the default path

    .. _fig-iar-install-dir:
    .. figure:: resources/iar_install_dir.png
       :align: center

       Default IAR Installation Location

    Make sure to select TI XDS as one of the debug probe drivers. You may also
    select other drivers. The driver will be installed towards the end of the
    installation of IAR.

    .. _fig_iar_debugger_options:

    .. figure:: resources/iar_install_debug_drivers.png
       :align: center

       IAR Debugger Options

3. Show Build Messages

    TI recommends showing all the build output messages for full verbosity
    during building. To do this, after importing a workspace, right-click in the
    Debug log window and select **All**.
    (see :numref:`fig-show-all-build-messages`)

    .. _fig-show-all-build-messages:
    .. figure:: resources/iar-show-build-messages.png
       :align: center

       Show All Build Messages in IAR  

.. _sdk-download-and-installation:

SDK - Download and Installation
===============================

The |SDK| can be downloaded from the following places:

* https://www.ti.com/tool/download/SIMPLELINK-LOWPOWER-F3-SDK
* `TI Resource Explorer <https://dev.ti.com/tirex>`_ then
  click Wireless Connectivity -> Embedded Software -> SimpleLink Low Power F3 SDK
* `GitHub <https://github.com/TexasInstruments/simplelink-lowpower-f3-sdk>`_

Build your first program for the |DEVICE| device
================================================

.. warning::
    The |DEVICEHIGH| has a Hardware Security Module (HSM) that requires 
    firmware to be flashed **after** a project flashed with a valid CCFG and 
    SCFG. This process will have to be followed after every mass chip erase 
    without retaining protoected sectors. This is not required for |DEVICELOW|.

.. note::
    The HSM image may be found in <sdk root>/bin/HSM. 

1. Open CCS.

#. In CCS, click Project > Import CCS Projects.

#. When prompted, browse your files to locate the folder 
   ``<SDK>\examples\rtos\LP_EM_CC2340R5\drivers\empty``.

#. Select the project then click "Finish".

#. The project will be imported and appear in the "Project Explorer".

        .. figure:: resources/cc2340rx/project_in_explorer.png
            :align: center
            :width: 50%

#. Build the project.

    - Set the project as the active project.
    - Select **Project -> Build All** to build the project.
    - As part of the prebuild process, SysConfig will run and generate code
      based on the ``.syscfg`` in the workspace. For more information on
      SysConfig, see the SysConfig chapter of the User's Guide.

#. Flash the HSM firmware (Only for |DEVICEHIGH|)

    - Open UniFlash 8.8 or later 
    - Select the correct LaunchPad or |DEVICEHIGH| device
    - Select **Settings & Utilities** and go to the **HSM Image** section
    - Enter the path to the HSM binary
        - This will be located in <sdk root>/bin/HSM.
    - Press **Program HSM Image**

        .. figure:: resources/cc27xx_UniflashHSM.png
            :align: center

            Program HSM Image with UniFlash 
      
Run your first program on the |DEVICE| device
=============================================

.. _quickstart_connectlptocomputer:

Connect the CC2340Rx to the computer
------------------------------------

This section provide a few options to connect your |DEVICE| device to a
computer. This is required to download code on the device, run a debugging
session, perform some power measurements, etc. 

Option 1 - With a Modular LaunchPad\ |trade| Emulator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you're using one of the new TI Modular Launchpads\ |trade|, you'll need
to connect the two sides of the Modular Launchpad\ |trade| together.

    .. figure:: resources/cc2340rx/modular_lp_mounting.png
        :align: center

Option 2 - With a TI LaunchPad\ |trade|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you do not have access to a Modular LaunchPad\ |trade| Emulator, you
can replace it by the upper part of a `CC26x2R LaunchPad`_ (or any TI
Launchpad where a XDS110 debugger is available on the board).

1. Unplug the CC26x2R LaunchPad board

2. Remove all the jumpers from the CC26x2R LaunchPad board, except the
   one powering the XDS110.

3. Connect the required signals of the CC26x2R LaunchPad board with the
   signals of the |LP|.

   The signals are named differently on the CC26x2R LaunchPad board and
   on the |LP|. Here how the signals should be connected.

    +-----------------------------+-----------------------------+
    | CC26x2R LaunchPad board     | |LP|                        |
    +=============================+=============================+
    | GND                         |  GND                        |
    +-----------------------------+-----------------------------+
    | 5V                          |  5V                         |
    +-----------------------------+-----------------------------+
    | 3V3                         |  3V3                        |
    +-----------------------------+-----------------------------+
    | RXD                         |  RXD                        |
    +-----------------------------+-----------------------------+
    | TXD                         |  TXD                        |
    +-----------------------------+-----------------------------+
    | RESET                       |  nRST                       |
    +-----------------------------+-----------------------------+
    | TMS                         |  SWDIO                      |
    +-----------------------------+-----------------------------+
    | TCK                         |  SWDCK                      |
    +-----------------------------+-----------------------------+
    | TDO                         |  *Not Connected*            |
    +-----------------------------+-----------------------------+
    | TDI                         |  *Not Connected*            |
    +-----------------------------+-----------------------------+
    | SWO                         |  *Not Connected*            |
    +-----------------------------+-----------------------------+

   Several alternatives are possible to achieve this

   * (Alternative 1) Use a 10-pin connector to connect the output of the XDS-110
     to the XDS-110 input of the CC2340Rx Launchpad.

        .. figure:: resources/cc2340rx/connect_option2_alternative1.jpg
            :align: center

            Connect the CC2340Rx LaunchPad using a 10-pin cable - The board on the left
            is a CC26x2R LaunchPad, the board on the right is the C2340Rx Launchpad.

        .. note::
            This does not connect the Tx and Rx UART signals to the debugger.
            These signals should be connected using a jumper wire.
            Usually, DIO22 is used for UART RX and DIO20 is used for TX.

    * (Alternative 2) Use a few jumper wires. The figure below shows the minimum
      required connections to perform software download. Additional connections
      will be required for reset and UART.

        .. figure:: resources/cc2340rx/connect_option2_alternative2.png
            :align: center

            Connect the CC2340Rx LaunchPad using jumper wires - The board on the left
            is a CC26x2R LaunchPad, the board on the right is the C2340Rx LaunchPad.


Flash the device
----------------

Using CCS, download the project on the device using the Debug button.

.. note::
    You may be prompted to update the XDS110 firmware – make sure to click "Update".

Flash a pre-compiled image
--------------------------

Option 1 - Using UniFlash
^^^^^^^^^^^^^^^^^^^^^^^^^

This is the recommended approach. It requires to install an additional tool
(UniFlash) but enables a more user-friendly interface.

Please refer to the procedure described `in the next section <./quickstart-intro-cc23xx.html#uniflash-for-device>`_.

Option 2 - Using CCS
^^^^^^^^^^^^^^^^^^^^

As shown before, CCS can be used to build and flash images on the device.
CCS can also be used to flash pre-built images.

.. important:: 
    Make sure to import a CC2340R5 example - in other word to follow the
    previous sections - before attempting to flash a pre-compiled image.
    Otherwise, CCS will miss the debugging configuration files and may not
    let you download the image on the target.

1. Click on the small arrow next to the "Flash" icon.

    .. figure:: resources/cc2340rx/flash_precompiled_image1.png
        :align: center

2. Browse to find the .out or .hex file you want

    .. figure:: resources/cc2340rx/flash_precompiled_image2.png
        :align: center


3. Click "OK". 

   A few operations should occur in background. 
   The progression of these can be seen at the bottom right of the CCS window.

    .. figure:: resources/cc2340rx/flash_precompiled_image3.png
        :align: center

   After that, you should get a window showing the progress of the download.
   No action is required, the download will occur automatically.

    .. figure:: resources/cc2340rx/flash_precompiled_image4.png
        :align: center


UniFlash for |DEVICE|
=====================

Download and Installation
-------------------------

#. Download `UniFlash`_

#. Execute the installer to install UniFlash in the default location (``c:/ti``).

Usage
-----

#. Select the device you are working with.

    .. figure:: resources/cc2340rx/uniflash_step1.png
        :align: center

#. Select the debugger used and click on "Start"

    .. figure:: resources/cc2340rx/uniflash_step2.png
        :align: center


.. _quickstart_smartrfstudio:

SmartRF Studio for |DEVICE|
============================

SmartRF Studio helps running RF tests on the |DEVICE|.

Download and Installation
-------------------------

#. Download SmartRF Studio 8 with support for |DEVICE| from the
   software product page on TI’s website.

#. Execute this file to install SmartRF Studio 8.

Device Connection
-----------------

#. Start SmartRF Studio 8. Below screenshot shows the UI without hardware
   connected.

   .. figure:: resources/smartrfstudio8/smartrfstudio8_startup.png
      :align: center

#. Connect the |LP| to the computer via the LP-XDS110 or LP-XDS110ET using the
   provided USB cable as described in :ref:`quickstart_connectlptocomputer`.

#. Click on the |inline_img_refresh| button next to ``DEVICE SELECTION`` and the
   debug probe will be listed as shown below:
   
   .. figure:: resources/smartrfstudio8/smartrfstudio8_connected.png
      :align: center

#. Double-click on |inline_img_devicename| to open the Radio Control Window.
   
   .. figure:: resources/smartrfstudio8/smartrfstudio8_radiocontrolwindow.png
      :align: center

.. |inline_img_refresh| image:: resources/smartrfstudio8/smartrfstudio8_refresh.png
.. |inline_img_devicename| image:: resources/smartrfstudio8/smartrfstudio8_device.png

.. _quickstart_smartrfstudiorfsettings:

RF Settings
-----------

.. |inline_img_addphy| image:: resources/smartrfstudio8/smartrfstudio8_addphy.png

Two default PHY settings are provided: 1 Mbps and 2 Mbps. Both at channel 17
(2440 MHz) and with an output power of 5 dBm. To change this settings, press the
|inline_img_addphy| button to the right of the one to be copied to `Create new
custom PHY based on this PHY`. Changing the channel and output power is now
possible as shown in :numref:`figure_smartrfstudio_customphy`

.. _figure_smartrfstudio_customphy:
.. figure:: resources/smartrfstudio8/smartrfstudio8_customphy.png
    :align: center
    
    Creation of custom Bluetooth LE PHY.

Continuous TX/RX
----------------

SmartRF Studio 8 can transmit a continous wave on a frequency and output power
selected in the :ref:`quickstart_smartrfstudiorfsettings`. Select the tab
``Continuous TX`` as shown in :numref:`figure_smartrfstudio_conttx`

.. _figure_smartrfstudio_conttx:
.. figure:: resources/smartrfstudio8/smartrfstudio8_conttx.png
    :align: center
    
    Transmission of a continuous wave.

The tab ``Continuous RX`` enables the reception of signals on a frequency
selected in the RF settings, see :numref:`figure_smartrfstudio_contrx`

.. _figure_smartrfstudio_contrx:
.. figure:: resources/smartrfstudio8/smartrfstudio8_contrx.png
    :align: center
    
    Receiving signals from another |LP|.

Bluetooth LE Packet TX/RX
-------------------------

Bluetooth LE packets can be transmitted in the ``Packet TX`` tab within ``RF TEST #1``
(see :numref:`figure_smartrfstudio_packettx`). This will transmit
non-connectable packets. The payload data can be changed in the UI.

.. _figure_smartrfstudio_packettx:
.. figure:: resources/smartrfstudio8/smartrfstudio8_packettx.png
    :align: center
    
    SmartRF Studio 8 in TX mode transmitting Bluetooth LE packets.

Bluetooth LE packet can be received in the tab ``Packet RX`` (see
:numref:`figure_smartrfstudio_packetrx`).

.. _figure_smartrfstudio_packetrx:
.. figure:: resources/smartrfstudio8/smartrfstudio8_packetrx.png
    :align: center
    
    SmartRF Studio 8 in RX mode receiving Bluetooth LE packets.

