.. _prop-examples-guide:

Examples User's Guide
=====================
The Proprietary RF examples utilize the `Radio Control Layer (RCL)`_.

The RCL offers low-level API's to run radio operation commands to setup 
the radio for transmit or receive.

Proprietary RF Examples
------------------

Proprietary RF examples are available for the `FREERTOS`, but can
also be used without any RTOS at all. That is possible with the |NORTOS_DPL|.

The Proprietary RF examples can be imported from the following SDK directory:
``{SDK_INSTALL_DIR}/examples/rtos/<PLATFORM>/prop_rf/``


:Carrier Wave:
    Basic example for RF performance measurements and testing,
    written directly on top of the RCL driver. Set the radio into various
    test modes. Transmission of modulated or unmodulated signal. Easy to change
    radio configuration.

    - `rfCarrierWave`_

..
   TODO: example not supported on CC23xx. may be supported later.
   :Dual Mode Rx/Tx:
       (CC1350 Only) Dual Mode Rx/Tx shows how to setup a multi-mode radio. This
       example in particular configures the radio with BLE and proprietary PHY.

       - `rfDualModeRx`_
       - `rfDualModeTx`_


:Echo Rx/Tx:
    The Echo Tx example transmits a packet and immediately switches over to
    receiver mode and waits for its echo. The Echo Rx example starts in receiver
    mode and transmits back any received packets (echo).

    - `rfEchoRx`_
    - `rfEchoTx`_

..
   TODO: example not supported on CC23xx. may be supported later.
   :Listen Before Talk:
       The Listen Before Talk (LBT) example illustrates how to implement a simple,
       proprietary LBT algorithm using the command chaining feature of the |PROPRFDEVICE|
       family.

       - `rfListenBeforeTalk`_


:Packet Error Rate:
    The Packet Error Rate (PER) example showcases different RF transfer modes of
    the |PROPRFDEVICE|. Multiple packets are transmitted or received and the packet
    error rate is calculated. The result is shown on an LCD/UART display.

    - `rfPacketErrorRate`_


:Packet Rx/Tx:
    Simple examples that show how to transmit and receive packets using the RCL.

    - `rfPacketRx`_
    - `rfPacketTx`_

..
   TODO: example not supported on CC23xx. may be supported later.
   :Synchronized Packet Rx/Tx:

       In this example you will learn how to build a time-synchronized connection
       between a transmitter and a receiver. This leads to the lowest possible
       power consumption on both sides. Time synchronization also builds the
       foundation for Frequency and Time Division Multiple Access, FDMA and TDMA
       respectively.

       - `rfSynchronizedPacketRx`_
       - `rfSynchronizedPacketTx`_

..
   TODO: example not supported on CC23xx. may be supported later.
   :Wake On Radio Rx/Tx:
       These examples showcase the Wake-on-Radio (WoR) functionality of the |PROPRFDEVICE|
       family to significantly lower the power consumption of an RF link by duty
       cycling the RF core. It shows how to use the RF Driver to schedule automatic
       wake-ups and send messages with long preambles.

       - `rfWakeOnRadioRx`_
       - `rfWakeOnRadioTx`_

..
   TODO: replace this with new SmartRF Studio 8 + RCL/LRF settings
   .. _rf_settings_what_and_how:

   RF Settings; What are they and how to use them
   ----------------------------------------------

   All proprietary RF applications require a set of RF settings, often referred
   to as "*smartrf_settings*", in order to achieve optimum performance for a
   specific PHY. Be aware that this is not only required for the proprietary PHY,
   but also all other PHYs, such as BLE, IEEE 802.15.4, etc.

   These RF settings, usually represented as a single pair of C header and source
   files in your project, must at minimum define a Setup Radio Operation command,
   RF core firmware patches, and RF core register overrides. Additional RF
   commands can be defined which are relevant to your PHY and application. See
   :doc:`PHY Configuration </rf-core/phy-configuration>` for a more in-depth
   explanation of how the actual configuration works.


   Exporting and Using RF Settings
   -------------------------------

   The main tool used for configuring, testing and exporting RF settings is
   SmartRF Studio. A dedicated SimpleLink Academy exists explaining the process
   on how to configure, export and include the exported RF settings into your
   application, see link below.

   - SimpleLink Academy: :sa:`Exporting RF settings from SmartRF Studio <modules/prop_01_basic/prop_01_basic.html>`


.. _running_examples_in_ccs:

Running Examples in Code Composer Studio (CCS)
----------------------------------------------

The following walks through importing and building one of the Proprietary RF
examples using the CCS IDE and the TI Resource Explorer.

#. If CCS is not already installed; download and install CCS from the
   `Code Composer Studio`_ tool page.

   If it is installed it is recommended that you install the available updates.

#. Download and install the |SDK| from here:

   ..
      TODO: replace this with actual SDK hyperlink
      http://www.ti.com/tool/simplelink-cc13x0-sdk.

   This step is recommended, but optional as the TI Resource explorer can
   download the examples from the resource explorer server. The rest of
   this section will assume that you have downloaded the SDK.

#. Open CCS, and use the menu option ``View-> Resource Explorer``.

#. Browse to the example of interest in the Resource Explorer.

    .. figure:: resources/trex-examples.png
       :align: center

       CCS Resoure Explorer Examples

#. Select the CCS or GCC compiler, we recommend using the CCS compiler, but
   compiling with GCC in the CCS IDE is also possible. Then select the example
   name and click the CCS icon in the top left to import it into your
   workspace.

   .. figure:: resources/trex-import.png
      :align: center

      CCS Project Selection

   ..
      TODO: replace this with instructions on FreeRTOS (e.g. FREERTOS_INSTALL_DIR)
      You will notice that 2 projects have been included in the workspace:

      * ``rfEasyLinkTx_CC1310_LAUNCHXL_tirtos_ccs``
      * ``tirtos_builds_CC1310_LAUNCHXL_release_ccs``

      As well as the example selected there is also the tirtos_builds project which
      is a platform and compiler specific TIRTOS build. This will only build once
      and is shared by all the projects for that platform and compiler in your
      workspace.

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

         CCS Project workspace

#. Build and download and debug the project by clicking on the 'bug'.
   The first time it will take some time due to the `FREERTOS` build.

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

      CCS Debug

#. Click run to run the example.

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

      CCS Run


.. _running_examples_in_iar:

Running Examples in IAR
-----------------------

#. Please make sure you're using the IAR version which is recommended in the |SDK| 
   release notes.If IAR Arm Workbench is not already installed, download and 
   install IAR Workbench for Arm from https://www.iar.com .

#. Download and install the |SDK| from here:

   ..
      TODO: replace with actual CC23xx SDK link
      http://www.ti.com/tool/simplelink-cc13x0-sdk .

#. Open IAR and create a new workspace with the menu option
   ``File -> New  -> Workspace``

   You can use this workspace for one or more examples.

..
   TODO: replace with more accurate SDK naming for:
      - <SDK>
      - SIMPLELINK_CC23XX_SDK
      - screenshot
#. Import the IAR Custom Argument Variables file with the menu option
   ``Tools -> Configure Custom Argument Variables``.  The location and file to
   be imported is ``C:/ti/<SDK>/tools/iar/SIMPLELINK_CC23XX_SDK.custom_argvars``.

   .. figure:: resources/iar-argvars.png
      :align: center

      Custom Argument Variables


#. Save the Workspace with the menu option
   ``File -> Save Workspace As...``.


#. To enable the Custom Argument Variables for this workspace close and open
   the workspace with the menu options ``File -> Close Workspace`` and
   ``File -> Open -> Workspace``.


#. Select the menu option ``Help -> Information Center`` and select the
   Integrated Solutions icon:

   .. figure:: resources/iar-integratedsolutions.png
      :align: center

      Integrated Solutions


#. Select the Texas Instruments Example projects and then click on the example
   applications link.

   .. figure:: resources/iar-ti.png
      :align: center

      Texas Instruments Examples

#. Follow the instructions on this page to import and build the project.


#. When you click on one of the examples, it will ask you to place a copy of
   the project file in another folder. Save it in a sub-folder of your workspace.
   If you are going to import only one example into your workspace, you can
   put the project file into the same folder as the workspace file.


#. Download and debug the example with the menu option
   ``Project -> Download and Debug``.

..
   TODO: make sure this process is still workable for CC23xx
      - replace TI-RTOS with FreeRTOS (if still needed to build)
   .. _running_examples_makefiles:

   Building Examples From the Command Line
   ---------------------------------------

   All examples can be built from command line using plain makefiles in 3 steps:

   1. Configure the toolchain paths
   2. Build the kernel (only when using TI-RTOS kernel)
   3. Build the example

   .. note::

      To avoid problems with spaces in paths, it is recommended to use a Unix shell like
      :wikipedia:`Bash <Bash_(Unix_shell)>` as command line environment instead of the native
      command interpreter `cmd.exe` in Windows.

   The toolchain paths are configured in a ``imports.mak`` in the SDK
   installation root folder. Open the file in an editor and modify the toolchain
   install paths lines depending on which toolchain you are going to use and
   where they are installed on your system.

   .. code-block:: make

      # The shown versions are just examples.
      XDC_INSTALL_DIR        ?= c:/ti/xdctools_3_50_03_33_core

      CCS_ARMCOMPILER        ?= c:/ti/ccsv7/tools/compiler/ti-cgt-arm_16.9.3.LTS
      GCC_ARMCOMPILER        ?= c:/ti/ccsv7/tools/compiler/gcc-arm-none-eabi-6-2017-q1-update
      IAR_ARMCOMPILER        ?= c:/Program Files (x86)/IAR Systems/Embedded Workbench 8.0/arm

   Once that is done, the TI-RTOS kernel can be built. This step is not necessary
   for No-RTOS examples.  In order to build the kernel, select a specific
   development board and build the ``release`` configuration. The makefile can be
   found in the folder
   ``<SDK_INSTALL_DIR>/kernel/tirtos/builds/<BOARD>/release/<TOOLCHAIN>``.
   Example:

   .. code-block:: sh

      $ cd /c/ti/simplelink_cc13x0_sdk_1_xx_xx_xx/kernel/tirtos/builds/CC1310_LAUNCHXL/release/gcc
      $ make

   Finally, the examples can be built. Navigate to the desired example and invoke `make`:

   .. code-block:: sh

      $ cd /c/ti/simplelink_cc13x0_sdk_1_xx_xx_xx/rtos/CC1310_LAUNCHXL/drivers/rfSynchronizedPacketRx/tirtos/gcc
      $ make -j4

   The resulting ``.out`` file is a regular
   :wikipedia:`ELF<Executable_and_Linkable_Format>` file that can be flashed to
   the device or converted into a binary or an Intel Hex file for other purpose,
   for instance, over-the-air download. Example for `objcopy` from the `GNU
   binutils` package:

   .. code-block:: sh

      $ arm-none-eabi-objcopy -S --gap-fill 0xff -O binary rfSynchronizedPacketRx.out rfSynchronizedPacketRx.bin
      $ arm-none-eabi-objcopy -S -O ihex rfSynchronizedPacketRx.out rfSynchronizedPacketRx.hex
