.. _LP-EM-CC1354P10: 			https://www.ti.com/tool/LP-EM-CC1354P10
.. _LP-XDS110ET: 		https://www.ti.com/tool/LP-XDS110ET
.. _HOST-SDK: 			https://www.ti.com/tool/SIMPLELINK-CC13XX-CC26XX-SDK
.. _CCS: 			https://www.ti.com/tool/download/CCSTUDIO/ 
.. _TI_Clang 1.3.0 LTS: 	https://www.ti.com/tool/download/ARM-CGT-CLANG-1 
.. _Python: 			https://www.python.org/downloads/release/python-3712/
.. _`CC33XX Host-Driver Porting Guide`: ../../porting-guide.html
.. _osi_filesystem:	        ..\/..\/doxygen\/cc33xx\/html\/group__OSI__FILESYSTEM.html
.. _LWIP: 			https://savannah.nongnu.org/projects/lwip/ 
.. _MCU_PLUGIN:                ..\/cc33xx-mcu-plugin.html 
.. _`BP-CC33XX`:  https://ti.com/product/CC3301

CC13xx and CC26xx Getting Started Guide
***************************************

Overview
========

This Getting Started Guide demonstrates how to start evaluating the **CC33xx in "Thick MAC" configuration** with **CC13xx/CC26xx** as the host MCU. 
The reference platform contains the CC1354 Launchpad (LP_EM_CC1354P10_6) and the CC3351 Booster pack (BP-CC3351).
Below are the instructions for building and running the Wi-Fi example (Network Terminal) from the CC33xx MCU package on the reference platform.
The MCU package is a plugin which is based on content (such as TI drivers for peripherals, FreeRTOS OS adaptation) available in the base SDK (simplelink_cc13xx_cc26xx_sdk_7_10_01_24).
Guidance about porting to other platforms is available through the `CC33XX Host-Driver Porting Guide`_.

Prerequisites
=============
**Hardware**
	* `LP-EM-CC1354P10`_
	* `LP-XDS110ET`_
	* `BP-CC33XX`_

**Software**
	* `HOST-SDK`_ (simplelink_cc13xx_cc26xx_sdk_7_10_01_24) 
	* CC33XX-MCU-Plugin 
	* `CCS`_ 11.1 and up (recommended CCS 11.2)
	* ``ARM GCC``: gcc-arm-none-eabi-9-2019-q4-major 
	* `FreeRTOS`_ (version 202104.00 recommended)

platforms/cc13x4_cc2x4 Folder Structure
=======================================
The plugin folder structure is described in `MCU_PLUGIN`_. This section focuses on the content of platforms/CC13x4_cc2x4:

* ``linker/``: cc13xx/cc26xx linker command files (.lds for gcc, .cmd for ticlang ``.lds``) 
* ``LP_EM_CC1354P10_6/``: - board-specific adaptation

	* ``LP_EM_CC1354P10_6/common.syscfg``: Launchpad's generic syscfg file (can be updated or overwritten for a specific example)
	* ``LP_EM_CC1354P10_6/port/``: board-specific adaptation sources (compiled and linked with the example code): osi_filesystem.c, spi_adapt.c, wifi_irq_adapt.c

* ``LP-CC2651P3-CC1354P10/``: - board-specific adaptation

	* ``LP-CC2651P3-CC1354P10/common.syscfg``: Launchpad's generic syscfg file (can be updated or overwritten for a specific example)
	* ``LP-CC2651P3-CC1354P10/port/``: board-specific adaptation sources (compiled and linked with the example code): osi_filesystem.c, spi_adapt.c, wifi_irq_adapt.c

* ``tools/cc33xx-firmware-programmer/``: a CCS project for programming the CC33xx firmware to the Launchpad's serial flash - to be imported and executed before running an example. 
* ``cc13x4_cc26x4.mak``: platform-specific makefile configuration (used by the makefile from the plugin root)
* ``cc13x4_cc26x4.cmake``: platform-specific cmake configuration
* ``CMakePresets.json``:  Presets for platform cmake configuration
							

Setup - CC13xx/CC26xx and CC33xx
================================
1. For the LaunchPad setup, please refer to  `LP-EM-CC1354P10`_.
   Note that ``LP_EM_CC1354P10_6`` does not contain a debug chip and requires connection to a `LP-XDS110ET`_ for the debugging interface (as shown in the `platform_figure`_).
2. Currently, the booster pack cannot be stacked on top of the launchpad (due to a conflict on a non-interface pin). 
   Instead, the following pins should be wired (see photo below): 
	
	+----------------------+------------------+
	| LP_EM_CC1354P PIN    | BP-CC3301 Pin    |
	+======================+==================+
	| J1_21 (5V)           | P1_21 (5V)       |
	+----------------------+------------------+
	| J1_21 (GND)          | P1_22 (GND)      |
	+----------------------+------------------+
	| J1_5  (DIO22)        | P1_5 (WLAN EN)   | 
	+----------------------+------------------+
	| J1_6  (DIO21)        | P1_8 (WLAN IRQ)  |
	+----------------------+------------------+
	| J1_7  (DIO10)        | P1_7 (SPI CLK)   |
	+----------------------+------------------+
	| J2_18 (DIO11)        | P2_18 (SPI CS)   |
	+----------------------+------------------+
	| J2_14 (DIO08)        | P2_14 (SPI_POCI) |           
	+----------------------+------------------+
	| J2_15 (DIO09)        | P2_15 (SPI_PICO) |           
	+----------------------+------------------+
	| J1_10 (DIO04)        | P2_14 (UART RX)  |           
	+----------------------+------------------+
	| J1_09 (DIO05)        | P2_15 (UART TX)  |           
	+----------------------+------------------+

.. _platform_figure:

The following photos show the connection of the LAUNCHXL-CC1354 (board in the back) and CC3351 Launchpad (board in the front):

	.. figure:: resources/IMG-LP_EM_CC1354P10_6__BP-CC3301.png
		:width: 360px
		:align: center
	
		LP_EM_CC1354P10_6 + BP-CC3301

.. note::
	Connect a PC to the XDS110 Launchpad's USB-C connector for powering up the platform and for collecting terminal logs.

CCS Preparation
===============
Before using the firmware programmer or any of the examples, the following parameters should be configured in CCS.
**In CCS -> Window - Select Preferences.
In Code Composer Studio -> Build -> Variables, define the following**:

	    +------------------------+------------------+---------------------------------+
	    | Name                   | Type             | Value                           |
	    +========================+==================+======+==========================+
	    | CC33XX-PLUGIN-ROOT     | Directory        | <path-to-plugin-root>           |
	    +------------------------+------------------+---------------------------------+
	    | FREERTOS_INSTALL_DIR   | Directory        | <path-to-freertos-installation> |
	    +------------------------+------------------+---------------------------------+

This must be done once and get updated if one of the paths changes.



Program the Flash
=================
Before running the example, the RAM bootloader, CC33xx Firmware, and initial configuration data file need to be programmed to the external flash on the LP_EM_CC1354P10_6.
This will be done using the **CC33xx Firmware Programmer** application (under ``platforms/cc13x4_26x4/freertos/boards-support/LP_EM_CC1354P10_6/tools/``).
This project already contains the CC33xx binaries (firmware, RAM bootloader, and conf file) converted to ``C`` arrays. The programmer writes the
content of the serial SPI flash using the TI NVS driver. See the flash offsets in the notes below - these offsets are used by the host driver (through `osi_filesystem`_).

1. Import the project
	1. In CCS, go to ``File->Import``
	2. Choose ``C/C++ -> CCS Projects``
	3. Browse... -> ``<CC33xx_Plugin>/platforms/cc13x4_cc26x4/tools/cc33xx-firmware-programmer/``
	4. Select ``CC33XX-FirmwareProgrammer_LP_EM_CC1354P10_6``
2. Build the project
3. Debug the project (load it to the platform and run it). Use the terminal to monitor the status.

.. note::
	1. The image is loaded and executed from the CC13XX/CC26XX internal execute-in-place (XIP) flash. 
	   To save XIP flash space (the CC33xx firmware is about 400KB) the binaries will be  stored in the external flash and read during the FW init.
	2. The binaries (available under tools/cc33xx_firmware) should be programmed to a pre-defined offset in the flash (which is already handled by the FirmwareProgrammer), as shown below:

	    +------------------------+--------------------------------+---------------------------------+-------------+
	    | Binary Name            | Description                    | Location                        | Offset      |
	    +========================+================================+=================================+=============+
	    | cc33xx_fw.bin          | CC33XX Firmware                | under tools/cc33xx_firmware/    | 0x00001000  |
	    +------------------------+--------------------------------+---------------------------------+-------------+
	    | cc33xx_2nd_loader.bin  | RAM Bootloader                 | under tools/cc33xx_firmware/    | 0x0008A000  |
	    +------------------------+--------------------------------+---------------------------------+-------------+
	    | cc33xx-conf.bin        | CC33xx initial configuration   | under tools/cc33xx_firmware/    | 0x000bA000  |
	    +------------------------+--------------------------------+---------------------------------+-------------+

	3. The application image should be loaded separately by the CCS debugger (see `run an example`_).

.. _run an example:

Run the example from CCS
========================
1. Import the project
	1. In CCS, go to ``File->Import``
	2. Choose ``C/C++ -> CCS Projects``
	3. Browse... -> ``<CC33xx_Plugin>/examples/``
	4. Select the example project for the combination of host platform and compiler (e.g. CC33XX-MQTTClient_LP-EM_CC1354P10_6_freertos_gcc)
2. Open a serial terminal (see `CC13xx/CC26xx Serial Terminal Configuration`_).
3. Build the project 

	.. note::
		| The build process requires linking the example code with libraries provided with the plugin.
		| These components currently includes the Wi-Fi Host Driver and `LWIP`_ networking stack (lwip, nimble).
		| The libraries are pre-built but can be modified and rebuilt if needed. See details in `Rebuilding the libraries`_ .
		| Other Libraries (such as Freertos, TI driver, and driverlib) are taken directly from the `HOST-SDK`_.
	
4. Debug the project 
5. Once the application (``.out`` file) is loaded to the CC13xx/CC26xx XIP flash, it can be restarted with an MCU reset (e.g. through the launchpad button or the CCS Debugger).
	
.. _`CC13xx/CC26xx Serial Terminal Configuration`:

CC13xx/CC26xx Serial Terminal Configuration:
---------------------------------------------
	| COM Port: 	  Listed as ``Applications/User UART`` (see note below)
	| Baud-rate:    115200
	| Data bits:         8
	| Stop bits:         1
	| Parity:         None
	| Flow Control:   None
	
	.. note::
		The COM port can be determined via Device Manager in Windows or via ls /dev/tty* in Linux.

.. _`Rebuilding the libraries`:

Rebuilding the libraries:
-------------------------
	A makefile (based on gnu make which is available in the XDCTOOLS installed with CCS) can be used to build the libraries and applications.
	In the plugin root folder you can find BUILD-gmake with instructions or just run ``gmake help``  to see detailed usage info.  
	Once the libraries (*.a files) are built, the CCS projects will find and link with the new libraries. 
	For cc13x4_26x4 - you can also build the examples (.out) using the makefiles (see the build-all script for supported configuration).

	| The sources of the wifi host driver are available under ``<CC33xx_Plugin>/Uuppemac/source/ti/drivers/net/wifi/``.
	| The sources of the wifi stack interface are available under ``<CC33xx_Plugin>/uppermac/source/ti/net/``.
	| The sources of the LWIP stack are available under ``<CC33xx_Plugin>/uppermac/source/third_party/lwip``. 
	| The sources of the NimBLE stack are available under ``<CC33xx_Plugin>/uppermac/source/third_party/nimble``.


 


