.. _sec-custom-hardware:

Custom Hardware
===============

This section will explain how to adapt a |STACK| application from the |SDK| to run on
custom hardware. In general, the steps required to migrate a |STACK| application
from a development kit to a custom board are minimal and involve changing the
pin configuration as well as selecting the correct RF configuration.
These steps, including a bring up guide, are detailed in the subsections below.

Designing a Custom Board
------------------------

Design guidelines for CC13x2 and CC26x2 boards can be found in the `CC13xx/CC26xx
Hardware Configuration and PCB Design Considerations`_ app note. This app note
includes RF front-end, schematic, PCB, and antenna design considerations. The
report also covers crystal oscillator tuning, optimum load impedance as well as
a brief explanation of the different power supply configurations.

.. note::
  A similar app note will be produced for the |DEVICE| devices. In the meantime,
  we recommend leveraging the reference designs available in the MSR folder.

Creating a Custom Board File
----------------------------

Board files are used by TI drivers to store device specific settings and I/O
mapping. The board file abstraction allows one TI-drivers implementation
to support many hardware implementations by just setting up new board files.
Examples utilize SysConfig to generate these board files. The generated
structures are placed in the ``ti_drivers_config.c`` and ``ti_drivers_config.h``
files. The SysConfig user interface can be utilized to determine pins and
resources used. Information on pins and resources used is also present in both
of these generated files. It is recommended to use SysConfig to generate the
board files for custom hardware as described
`here <https://software-dl.ti.com/ccs/esd/sysconfig/docs/guide/custom-board.html>`_.

.. only:: sdk_includes_ble

  Clock accuracies and Bluetooth LE
  ---------------------------------

  The |CORESPEC| defines two clock accuracies, the "Active clock accuracy"
  (|CORESPEC| Vol 6, Part B, §4.2.1) and the "Sleep clock accuracy"
  (|CORESPEC| Vol 6, Part B, §4.2.1).
  In general, the HF XTAL (high frequency crystal oscillator) is used as active
  clock and the LF XTAL (low frequency crystal oscillator) is used as sleep
  clock. Tuning of the HF XTAL and LF XTAL is discussed in the 
  `HW Configuration Guide <https://www.ti.com/lit/swra640>`_.

  The |CORESPEC| require the active clock to have a drift less than or equal
  to ±50 ppm and there is no way (nor need) to specify its accuracy to the
  |BLE5_STACK|.

  The |CORESPEC| require the sleep clock to have a drift less than or equal
  to ±500 ppm. The accuracy of this clock has a real impact on the timing of
  the radio operations. This is why its accuracy should be communicated to
  the |BLE5_STACK| using the function :ble_api:`HCI_EXT_SetSCACmd`.

  As mentioned before, the accuracy of the sleep clock has an impact on the
  timing of the radio operations. This effect is called window widening and is
  described in details in the |CORESPEC| Vol 6, Part B, §4.2.4.

    *The Link Layer is expecting to receive a packet within a certain window
    (extending from receiveWindowStart to receiveWindowEnd) or at a certain time
    (in which case receiveWindowStart and receiveWindowEnd are both that time)
    but, because of active clock accuracies and sleep clock accuracies there is
    uncertainty as to the exact timing of that window at the sending Link Layer.
    The recipient should therefore adjust its listening time to allow for this
    uncertainty. The increase in listening time is called the window widening.
    Assuming the clock inaccuracies are purely given in parts per million (ppm),
    it is calculated as follows:*

      .. math::

        \textrm{transmitterAllowance} = (\textrm{txCA} / \textrm{1000000}) * (\textrm{receiveWindowEnd} - \textrm{timeOfLastSync}) + \textrm{J us}

    *where J shall be 2 when the active clock applies and 16 when the sleep clock
    applies and the other parameters are specified in Table 4.1. of* |CORESPEC|
    *Vol 6, Part B, §4.2.4.*

  The connection parameters can be chosen independently of the clock accuracy
  – absolutely all the combinations of clock accuracy and connection parameters
  are allowed. As can be observed in the formula, for a given clock accuracy,
  the listening window length is proportional to the effective connection
  interval. At a certain point this might have a significant impact on the
  energy consumption.

  RF Temperature Compensation
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^

  If the selected HFXT source is not accurate enough for the selected RF
  protocol, RF Temperature Compensation may be enabled via ``SysConfig`` -> 
  ``TI Devices`` -> ``Device Configuration``. RF Temperature Compensation
  compensates HFXT frequency for temperature during
  radio transmissions. This improves the accuracy of the CLKSVT and CLKREF over
  temperature. It can be configured using the following parameters:

  * HFXT Compensation Threshold: HFXT will only be automatically compensated
    when the measured device temperature exceeds this threshold (in degrees
    Celsius). This can help to reduce power consumption if temperature
    compensation is not required below a certain temperature. If set to -41,
    then compensation will be enabled across the entire operating temperature
    range of [-40, +125].

  * HFXT Compensation Delta: HFXT will be automatically compensated if the
    temperature drifts more than this delta-value in either direction (in
    degrees Celsius). For example, if the temperature is measured to 30 degrees
    when the device boots (measured within ``Board_init()``), but later drifts
    to 30 + delta or 30 - delta, then HFXT temperature compensation will be
    performed, and the temperature setpoint updated accordingly.
  
    .. note::
      Temperature is calculated using the Temperature driver. Please see
      :tidrivers_api:`Temperature.h` for more information.

  * Custom HFXT Coefficients: If the ppm offset of the HFXT can be approximated
    by a third order polynomial function of temperature (degrees Celsius),
    ppm(T) = P3T^3 + P2T^2 + P1*T + P0, where the coefficients P3, P2, P1, and
    P0 are known, they can be supplied in ``SysConfig``. The default
    coefficients represent the characteristics of the 48 MHz crystal (part
    number TZ3908AAAO43) mounted on the LP_EM_CC2340R5 LaunchPad.

    .. note::
      Each crystal will have different parameters. You may request the
      parameters for your specific crystal by contacting the
      crystal vendor/manufacturer.

.. This part is not yet applicable and will require re-work as the clock names have changed

  .. only:: sdk_includes_ble
  
    Using 32-kHz Crystal-Less Mode
    ------------------------------
  
    |STACKVER| includes support for operating the |DEVICE| in a 32-kHz
    crystal-less mode for peripheral and broadcaster (beacon) role configurations.
    By using the internal low-frequency RC oscillator (RCOSC_LF), the 32-kHz crystal
    can be removed from the board layout.
  
    There are a few steps that must be taken to enable this feature.
    For any peripheral project, the following change is required for IAR.
    For CCS user, please see the
    `Running Bluetooth Low Energy on CC2640 Without 32 kHz Crystal <http://www.ti.com/lit/pdf/swra499>`_
    for the needed steps to enable RCOSC_LF in your project.
    You will find more detail regarding this feature in the aforementioned application note.
  
    1. Include ```rcosc_calibration.c``, ``rcosc_calibration.h`` and
       ``ccfg_app_ble_rcosc.c`` files which locate at
       *<SDK\_INSTALL\_DIR>\\source\\ti\\ble5stack\\common\\cc26xx\\rcosc*
  
    2. Exclude ccfg_app_ble.c from build.
  
    3. Add USE_RCOSC to the ``.opt`` file containing the application defines.
  
    4. Add the following code to your peripheral project.c
  
       .. code-block:: c
            :caption: RCOSC calibration include
            :name: include RCOSC_calibration
  
            #ifdef USE_RCOSC
            #include "rcosc_calibration.h"
            #endif //USE_RCOSC
  
    5. Add the following code to your peripheralproject_init function in peripheral project.c
  
       .. code-block:: c
            :caption: RCOSC calibration enable
            :name: enable RCOSC_calibration
  
            #ifdef USE_RCOSC
            RCOSC_enableCalibration();
            #endif // USE_RCOSC
  
    6. If using a custom board file, enable the RCOSC in the power policy.
       When using SysConfig to generate a board file, be sure to select
       ``Calibrate RCOSC_LF`` in the TI Drivers -> Power settings menu in SysConfig.
  
    7. Constrain the temperature variation to be less than 1°C/sec. If the
       temperature is to change faster than 1°C/sec, then a short
       calibration interval must be used.
       Calibration interval can be tuned in rcosc_calibration.h
  
       .. code-block:: c
            :caption: RCOSCLF calibration interval
            :name: RCOSCLF calibration interval setup
  
            // 1000 ms
            #define RCOSC_CALIBRATION_PERIOD   1000
  
    .. note::
        Use of the internal RCOSC_LF requires a sleep clock accuracy (SCA) of 500 ppm.

Configuring Device Parameters for Custom Hardware
-------------------------------------------------

  1.  Set parameters, such as the sleep clock accuracy of the 32.768-kHz
      crystal. 

  2.  Define the CCFG parameters in Device Configuration in SysConfig.

.. note::
    For a description of CCFG configuration parameters, see the |TRM|.

.. _sec-creating-a-custom-ble-app-rf-front-end-and-antennas:

Initial Board Bring Up
----------------------

When powering up a custom board with the |DEVICE| for the first time, it is
recommended to follow the Board Bring-Up section on `CC13xx/CC26xx Hardware
Configuration and PCB Design Considerations`_. After confirming that the board
is being powered correctly by the battery or power supply and can be identified
by the SWD tool, programming the device with a minimal SW application to verify
stability is also suggested.

.. only:: sdk_includes_ble

  TI recommends using the basic_ble sample application for initial board
  bring up with modifications to the ``ti_drivers_config.c`` file to:

  1. Disable all GPIO pin access
  2. Select the correct RF front end setting (done by SysConfig)


  The TI |STACK| does not require any GPIO pins to be configured in order to
  establish and maintain a BLE connection. Ensure that ``Display_DISABLE_ALL``
  is defined in the application Predefined Symbols so that diagnostic logging
  data is not routed to any GPIO pin. If your custom board uses a different device
  configuration, such as the 32 kHz crystal-less RCOSC_LF configuration, be sure
  to make these device changes to the project. With this minimal application
  configuration you should be able to establish a BLE connection
  (e.g., with a smart phone or BTool) to your board at the expected range.
  If you are not able to complete this step, then it is likely there is a
  misconfiguration of the RF front end or you have other board related or layout
  issues.

  After confirming that your board can maintain a BLE connection, you can now
  validate that your BLE application functions as expected on the custom board.
  Again, it is suggested to enable your GPIO pins one at a time in the board file
  and comment-out access to other GPIO pins in your application. If you do
  encounter a CPU exception (HWI abort) during this phase it is likely that a
  GPIO pin is incorrectly mapped in your custom board file or your application is
  attempting to access a GPIO pin that does not exist in your device package type.

Using the RGE QFN24 package variant
-----------------------------------

The |DEVICE| is also available with a 4-mm x 4-mm RGE QFN24 (12 GPIOs) package 
variant. See the `CC23xx Datasheet`_ for all the package options and IO descriptions.

In order to build |SDK| project using the RGE package, a few settings must be made
in SysConfig.

* First open the SysConfig file, click the icon on the top right hand corner ``Show Board View``
* Click the button ``SWITCH``
* Select ``NONE`` in the Board | New Value field
* Select the ``CC2340R5RGE`` device in the Device field. It automatically updates the package to ``RGE``.
* Finally click ``CONFIRM``

.. _fig-SysConfig_RGE_Package_Switch_CC23xx:
.. figure:: resources/SysConfig_RGE_Package_Switch_CC23xx.png
    :align: center

    Switch to RGE Package

After clicking ``CONFIRM``, the pins of the SysConfig file may change. If error
messages appear, check that the pins changed in SysConfig are consistent with
the implemented hardware design.

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

    Check the new configuration generated by SysConfig

For each error, review the suggested configuration value,
and accept it or modify it.
  

