Go beyond Serial.print() with new Energia sketch import feature in Code Composer Studio v6 In Code Composer Studio v6 or newer (CCSv6+), developers have the ability to import existing Energia sketches into the IDE. This opens up additional functionality and true hardware debug capability such as setting breakpoints, watching variables & stepping through code line-by-line. The CCS debugger also enables developers to “step-into” an Energia API to see the under-lying bare metal code that is ultimately programmed into the microcontroller device. This added functionality enables a non-intrusive debug environment that takes developers to the next level beyond Serial.println().

Quick links

Here’s a quick video of it in action:

Keep on reading to get started! Step 0: Download & Install the latest version of Code Composer Studio (v6 or greater) Link: www.ti.com/ccs  We recommend the “Web Installer”, which will enable a more customized download, only pulling in components that you care about. Be sure to select the appropriate components during install for your setup (MSP430, Tiva, etc) If you don’t already have Energia, be sure to download & install the latest version of Energia as well. Step 1: Point CCS to your Energia installation path Once CCS is installed, we will have to point the IDE to your Energia install path. This will ensure that CCS is pulling in the appropriate include files, such as libraries, Energia example sketches, board definition files, etc. To do this, open up CCS. The first thing we will need to do is set a “Workspace”. A workspace is where all of our CCS projects will be saved in your computer. Once a workspace is created, the CCS environment will open up. To point CCS to your Energia install path, navigate to Window > Preferences.  This will open up the Preferences window. Select Energia. At this point, navigate to the root folder of your Energia install as shown in the screenshot below.

Point CCS to your Energia install path.

Point CCS to your Energia install path.

Step 2: Let’s import an Energia sketch! Now that CCS knows where Energia is, we can start importing an Energia sketch. This can be any of the Energia examples or one of your own custom Energia projects. To do this in CCS, we simply navigate to File > Import > Energia > Existing Energia Sketch. This will open up the Import pop up menu. From here, we need to first tell CCS which LaunchPad we are using. In this example, we are using the MSP-EXP430F5529LP LaunchPad.

Before we import any projects, we need to select which LaunchPad you are using.

Before we import any projects, we need to select which LaunchPad you are using.

Now that CCS knows which LaunchPad we are developing on, we can start importing projects. We can either “Browse” for a specific Energia example, or we can import one of the “Examples” that is packaged with Energia.  For this example, let’s import the Energia “blink” sketch by clicking on the “Examples” button. This will provide a complete list of the Energia examples that are available.

We can import one of the many example sketches that come with Energia.

We can import one of the many example sketches that come with Energia.

Once we select the Energia sketch we want to import, the project will appear in the “Project Explorer” window within CCS. Also, the Energia sketch will be converted to a *.cpp file.

The Energia sketch is converted to a .cpp file and appears in the CCS Project Explorer window.

The Energia sketch is converted to a .cpp file and appears in the CCS Project Explorer window.

Step 3: Debugging an Energia sketch! Now that the Energia sketch is imported, developers can now modify their Energia sketch within the CCS code editing window. All of the same functions/APIs provided by Energia are available here. CCS also provides a few nifty features such as “Auto-complete”. To use, simply start typing an Energia API. While you are typing, pressing “CTRL+Space” will provide a drop-down of suggested auto-completed functions/expressions.

CCS provides "Auto-complete" capability by pressing "Ctrl+Space" while partially typing a function.

CCS provides “Auto-complete” capability by pressing “Ctrl+Space” while partially typing a function.

In addition, developers can also inject in-line C for bare “to-the-metal” programming of the microcontroller. In the screenshot below, we are replacing the Energia API pinMode() with the direct P1DIR register modification that accomplishes the same thing on an MSP430 microcontroller. This enables the developers to leverage Energia abstraction or low level C code as-needed. *Note that this functionality of in-line C programming is also available within Energia.

Developers can also inject in-line C for bare metal programming of the microcontroller.

Developers can also inject in-line C for bare metal programming of the microcontroller.

Once you are ready to load your code into the microcontroller, we can click the green “Debug” button.

Compile & upload your Energia sketch by clicking the green "Debug" button.

Compile & upload your Energia sketch by clicking the green “Debug” button.

By clicking the Debug button, CCS will switch to a Debug view. This will expose a few new control buttons. By default the code does not start executing. The develop must push the “Run” button to start code execution. In addition, developers have a few other control buttons:

  • Run: Starts code execution. This code will run forever unless there is a breakpoint set or a user halts code execution.
  • Suspend/Pause: This will suspend the code and will highlight the last line of code that was last executed.
  • Terminate: This will terminate and end the hardware debug session.
  • Step over: This will execute one line of code at a time.
  • Step into: This will jump into a function or block of code for greater control and granularity. For example, stepping into the delay() function of Energia will expose the underlying bare-metal C code and allow the debugger to step through this more granular C code line-by-line.
  • Step return: This will jump the user out of the function or code block that you are stepped into.
Have greater control of your code with full hardware debug capability.

Have greater control of your code with full hardware debug capability.

For greater control and understanding of what your application is doing, developers also have the ability to set a breakpoint. This is a specific location in your code that you can pause execution. In this paused state, you can peer into the memory block of the microcontroller, look at variable values, register states & more. To set a breakpoint, simply double-click the line number of code you want code execution to pause at every time the program counter hits that line of code. A breakpoint will be visualized by a blue dot. Now, when you hit “Run” to start code execution, code will run until the breakpoint is hit.

To set a breakpoint, double-click the line number of the line of code you want to break at.

To set a breakpoint, double-click the line number of the line of code you want to break at.

We can even “right-click” a line of code and select “Run to Line” to execute code up until the selected line of code. Step 4: Peering into your microcontroller non-intrusively The true value of hardware debugging is that developers can peer into the inner workings of the microcontroller during code execution. Energia provides a simple debug capability through Serial.println() by sending diagnostic data to a Serial Monitor while code is running. This helps in some regard, but is a very intrusive option (i.e. it adds to code size, could alter timing, etc). CCS, like Energia, also comes with a built-in terminal application. The terminal can be found by navigating to: Windows > Show Views > Other… > [Search for “terminal” in the filter field] This will open up a terminal window. To use it, we need to configure it properly. The settings we used were the following:

  • Encoding: UTF-8
  • Connection Type: Serial
  • Port: Check your Device Manager to find out which COM port your MCU’s UART interface is connected to.
  • Baud Rate: This should match the baud rate that is set in your code.
  • Data bits: 8
  • Stop bits: 1
  • Partity/Flow Control: None/None
  • Timeout (sec): 5 (default)
CCS provides a built-in terminal, much like Energia's built in Serial Monitor.

CCS provides a built-in terminal, much like Energia’s built in Serial Monitor.

With this built-in Terminal in CCS, users will be able to send/receive diagnostic data using Serial.println() just like within Energia. Taking it to the next level… Energia introduces us to the world of “print line debugging” with Serial.println(), which allows developers to send diagnostic information back to a PC Serial Monitor. However, this form of debugging is intrusive. CCS allows users to debug code without having to inject intrusive code into an application. Instead, CCS users can set break points and set up “Watch Expressions” to peek into the memory addresses of the microcontroller and see the variables and registers change during code execution. To demonstrate this, we modified the blink LED example to include a counter (loopCount) that increments for every cycle of the loop(). In Energia-land, we would use Serial.println(loopCount); to send this data back to a Serial Monitor or Terminal. However, with CCS, we have access to the full features of the hardware debugger available on the LaunchPad.   To watch a variable, simply right-click the variable you want to watch, then select “Add Watch Expression”. This will add your variable to the “Expressions Window”. To see he value of your variable at a given time, set a breakpoint or pause your code manually. The “Expressions” window should open and we’ll see the value of our watched variable (loopCount) should update anytime we pause our code or hit a breakpoint. In the screenshot below, we are watching loopCount two different ways. We are using Serial.println() to send loopCount to the integrated Terminal of CCS (similar to what we would have done in Energia). We are also using the “Watch Expressions” window in CCS to watch the values of loopCount. Note that they both show the same number… The main difference however is that watching a variable doesn’t require any intrusive code to be added to our sketch, which means that our code stays lean and un-affected by our debugging.

Serial.println() to a built-in terminal VS using true hardware debugging for watching variables.

Serial.println() to a built-in terminal VS using true hardware debugging for watching variables.

Step 5: Other cool debugging features CCS is an extremely powerful tool that can help take your Energia sketches to the next level. In addition, CCS could be a great tool for developers creating new Energia libraries or working on porting Energia to new TI processors. The ability to have true debug makes development much easier. Here are a few other capabilities that CCS brings to the table. Peeking into the individual microcontroller registers. During code execution, we can also peer into the individual registers of the microcontroller and see how the bits and bytes alter as code executes line-by-line. To enable this view, go to the following menu item: Window > Show View > Other… > “Registers” This will open up a new window in CCS called “Registers”. Here, we can explore the individual registers of the microcontroller. In the screenshot below, we can see that as bits change in the various registers, the bit field is highlighted in yellow to signify a change in contents. This is a powerful debugging tool to ensure your microcontroller is operating as expected.

CCS also enables developers to peek into the individual registers of the microcontroller during code execution.

CCS also enables developers to peek into the individual registers of the microcontroller during code execution.

Peeking into the microcontroller memory block. In addition, we can also peer into the memory block of the microcontroller and see how its contents change as code executes line-by-line. To enable this view, go to the following menu item: Window > Show View > Other… > “Memory Browser” This will open up a new window in CCS called “Memory Browser”. Here, we can explore the contents of the microcontroller memory block. In the screenshot below, we can see that as memory contents change, the memory address is highlighted in yellow to signify a change in contents. This is yet another powerful debugging tool to ensure your microcontroller is operating as expected. notice that we can change how the bits are visualize in the Memory Browser window (i.e. binary, hex, unsigned integers, etc).   Step 6: What’s next?  At this point, the possibilities are endless! Hopefully this guide provides a glimpse at what is possible with true hardware debug capability. For more information in the full capabilities of Code Composer Studio, be sure to check out the available resources @ the CCSv6 wiki    Step 7: Getting support  If you need further assistance, be sure to check out the official TI Engineer2Engineer (E2E) online community:  http://e2e.ti.com/  

Quick links