<.
]]
Requirements
------------
Software:
* Special Code Composer Studio Theia v1.1.0 "All-ISA" build (internal release only)
* [Windows](https://software-dl.ti.com/ccs/non-esd/misc/ccs_theia/allISA-CCSTheia1.1.0.00001_win64.zip)
* [Linux](https://software-dl.ti.com/ccs/non-esd/misc/ccs_theia/allISA-CCSTheia1.1.0.00001_linux-x64.tar.gz)
* [macOS](https://software-dl.ti.com/ccs/non-esd/misc/ccs_theia/allISA-CCSTheia1.1.0.00001_osx.zip)
Hardware
* Supported TI device
* MSPM0
* MSP430
* MSP432
* C2000
* CC32xx
* CC13xx/CC26xx
* AM2x
* Internet access
[[y C2000 Issues:
There are several known issues when trying to work with C2000, especially when tying to work with C2000Ware projects.
]]
Lab 1: Importing and Running an Example Project
---------------
This lab will go over importing an example project and flashing the program to the target (TI device) to run the program.
The default steps use the CCS Theia **Project Wizard** to download the SDK for your device and import an example. This will require an internet connection.
1. Connect your TI device to the computer via USB cable.
2. Open Code Composer Studio Theia.
3. In the **Getting Started** view, select the **Create a new project** option or go to **File → Create New Project**. This will open **Project Wizard**.
[[y NOTE:
Currently, only MSPM0 devices can be auto-detected or selected in the Getting Started Page.
]]
4. Select your device.
5. **Project Wizard** will then display a list of examples for the specified device. Select your desired example project. Press **CREATE** to continue.
If no examples are displayed for your device, make sure your selection is listed under **Device** (NOT under **Board**). This typically happens when a board (instead of a device) is selected for C2000Ware examples.
[[+y If you are still unable to view examples, you can try importing a project from **Resource Explorer**. (Expand):
1. Navigate to **View → Resource Explorer**.
2. Select your device to filter the content.
3. Browse through the SDK for your device, select an example project and import it to CCS Theia.
You can also install your SDK manually and import an example without using **Resource Explorer**.
+]]
[[+y If there are issues importing/using examples from **Resource Explorer**, or to use a custom project, use the manual steps instead to install the SDK for your device and import an example (without **Resource Explorer**) (Expand):
1. Download and install the SDK version that is compatible with your TI device, and take note of the install location.
2. Connect your device to the computer via USB cable.
3. Open Code Composer Studio Theia.
4. From the top menu bar, select: **File → Preferences → Code Composer Studio Settings**
5. In the dialog, select the **Products** node in the left panel and check to see if there is an entry for the installed SDK under the list of **Discovered products**. If it does not appear in the list, press the **Refresh** button to have CCS Theia look for newly installed packages.
[[y NOTE:
If the SDK was not installed in one of the parent directories listed in the **Product discovery-path** list, the parent directory path of the SDK will need to be added to that list before the **Refresh** attempt.
]]
After the SDK has been discovered, press the **OK** button to close the **Preferences** dialog.
6. From the top menu bar, open: **File → Import Project(s)**.
7. Click **Browse...** and navigate to the location of the SDK install. From there, you can find an example project to import into CCS Theia.
Navigate to the appropriate example folder.
Click **Select Folder** then **Finish** to import the project.
Now skip to step 8 below.
+]]
6. ***Skip directly to step 8 if the SDK for your device has been manually pre-installed and discovered by CCS***:
If the SDK was not manually pre-installed, a prompt will appear indicating that the SDK package must be installed locally to proceed with the import. Press the **Install** button to proceed.
Another prompt will appear, displaying information about the package (and any dependencies) to be downloaded and installed. Press the **Install** button to proceed with the download and installation of the SDK package.
[[y NOTE:
Confirm that the version of the SDK to be installed is compatible with your specific device. If it is not, then you'll need to manually download and install a version of the SDK that is compatible.
]]
This process will take several minutes. A dialog will appear when the SDK has been successfully downloaded and installed.
7. Another dialog will appear to prompt for confirmation to proceed with the project import. Press the **Import** button to continue.
8. Check the **Explorer** in the **Side Bar** and confirm that the example project is there.
The example project has now been imported to the workspace.
9. Browse through the project in the **Explorer**.
If your project is a SysConfig project, you can open the `.sysconfig` file, which is a tool to simplify the configuration of you application on a device. In the SysConfig file, you can also see the pins and resources being used by clicking **Show Device** at the top right corner.
More information regarding SysConfig can be found at this [SysConfig](https://software-dl.ti.com/ccs/esd/documents/users_guide_ccs_theia/ccs_project-management.html#sysconfig "SysConfig") page.
10. Bring up the context menu (ex: mouse right-click) for the project in the **Explorer** and select **Debug Project** (or select **Run → Debug Selected Project** in the top menu bar). This will prompt to save source files, build the project, start the debugger, switch to the **Debug** view in the **Side Bar**, connect CCS Theia to the target, and then flash (load) the program to the target.
When running in debug mode, your LaunchPad is at first suspended. Click on the blue **Continue** icon near the top left of the **Debug** view, or click **Run → Continue** in the menu bar, for your device to run the program.
* There are icons on the left sidebar which allow you to switch between the **Debug** and the **Explorer** views.
* You can **Pause** and **Continue** program execution on the target as desired.
11. When you are done with this part of the lab, **Stop** the debug session and return to the **Explorer** view.
Click **Run → Debug Selected Project** and then **Run → Continue** to build the project, start the debugger, and run the program on the target.
That's it!
[[b NOTE:
You can find very useful code snippets by browsing through the other example projects in the SDK. There are simple projects that utilize hardware resources such as the ADC, timers, I2C, SPI, etc.
]]
Lab 2: Basic Debug Concepts
---------------
This lab will cover the basics of debugging. Specific tools and concepts that are covered are:
* Breakpoints
* Debug view
* Disassembly view
* Other Views
### Breakpoints
Breakpoints are specific points that can be set in the code, where the program is to halt execution. Once halted, the values in registers/memory/etc. can be inspected to gain a deeper understanding of the program execution. This is very useful when debugging.
[[y Hardware Breakpoints
A hardware breakpoint is required when setting a breakpoint in Flash. The number of available hardware breakpoint resources varies per device.
]]
1. If your device is currently running, ensure you are in the **Debug** view and **Pause** it. Otherwise, click on **Run → Debug Selected Project** to flash the program to the target and pause it.
2. Click on the **Breakpoints** panel under the **Debug** view to expand it. There should be no breakpoints to start.
3. While staying in the **Debug** view, in the source code editor click on the margin to the left of the line number to insert a breakpoint. This will halt program execution whenever it reaches this point in the code.
4. Click **Run → Continue** to resume program execution on the device. Note that the program will suspend when it reaches the breakpoint.
5. By clicking **Run → Step Into** or **Run → Step Over** (or using the related buttons in the **Debug** view), the target will do the associated source step. Click **Run → Continue** to resume program execution.
* **Step Into** steps to the next line of code, including stepping into a new function call.
* **Step Over** steps to the next line of code in the current function, but will not step into a new function call. It will remain in the current function until it ends or returns.
* **Step Out** steps out of the current function before it reaches its end, and suspends execution on the next statement of the calling function.
6. After you are finished with this part of the lab, in the **Breakpoints** panel, remove the breakpoint. You can also remove it by clicking the margin next to the line number where the breakpoint currently exists.
### Debug View ###
In addition to the target execution toolbar and providing information on **Breakpoints**, the **Debug** view also provides more information in the following collapsable views:
* **Threads**: This view will show the current debug session and the status the CPU.
* **Call Stack**: This view will provide the current call stack information for the program.
* **Variables**: This view will display all local variables and related values.
* **Watch**: This view allows you to add/view desired expression.
* **Breakpoints**: This view allows you to view/enable/disable/remove breakpoints.
### Disassembly View
1. If your device is currently running, ensure you can see the **Debug** view and that execution is **Paused**. Otherwise, click on **Run → Debug Selected Project** to flash the program to the target and pause it.
2. Click on **View → Disassembly** to open the **Disassembly** view. By default it will show the disassembly of the current location in the code. The location of the Program Counter is indicated with a small yellow arrow(s). Symbols will be highlighted in green text.
3. You can enter in an address or symbol in the location box at the top of the **Disassembly** view to change the address that the view starts at. Enter **main** to display diassembly content starting from the **main** symbol.
4. Note the toolbar with button to **Refresh view**, **Goto current PC location**, **Assembly step-into**, and **Assembly step-over**.
5. To toggle source interleaving, bring up the context menu in the **Disassembly** view and select **Show source** in the context menu. This will interleave the source lines with the disassembly. Source lines will be highlighted in yellow text.
### Other Views
Several other views are available under the **View** menu. Experiment with the various views such as:
#### RTOS Objects View
The **RTOS Objects View** is available if you are using a FreeRTOS project. It displays the current state of the real-time kernel running on the target if one is used with the target application. It not disturb the run-time behavior of the application on the target and adds zero footprint to the target code (when using a JTAG connection). **RTOS Objects** shows the FreeRTOS Module, and you can see ISR Stack, Heap Stats, Task Module and Task Instances.
#### Register View
The **Registers** view is used to display and edit the values of core and memory mapped (peripheral) registers. Click on **View → Register** to open the view.
#### Memory View
The **Memory** view is used to display and edit the values memory. Click on **View → Memory** to open the view.
Lab 3: Extensions
-----------------
You can search for and install extensions from the **Extensions** icon on the Activity Bar. For example, you can search for the popular TODO Highlight extension.
This extension will help you keep track of the things in your file that you want to do and fix by highlighting text like 'TODO:'' and 'TOFIX:'.
Extensions can easily be uninstalled by going to the **Extensions** icon, searching the extension or finding it in the **Installed** tab, and clicking uninstall. There are many extensions available for a wide range of functionalities. You can browse the available extensions at https://open-vsx.org/.
In order to browse extensions, you may need to set a proxy. You can do this by searching "proxy" in **General Settings**.
### Summary
Lab 1 covered using Code Composer Studio Theia to import an example project and flash it to a target to run the program. Lab 2 provided information on the basics of using debug tools in Code Composer Studio Theia. Lab 3 covered how to install extensions in Code Composer Studio Theia.
<!-- End of markdown source -->
<div id="footer"></div>
]]>