<![CDATA[
<!-- Start of markdown source -->
<!-- Stylistic notes:
- Use the 'text' syntax highlighting for blocks of code from the command prompt
- For Informational notes try to use blue alerts or callouts ({{b }} or [[b ]])
- For warnings or error troubleshooting try to use yellow alerts or callouts ({{y }} or [[ y]])
-->
Overview
---------------
DSS is a set of Java APIs into the debug server (the debugger) which allows scripting through third party tools. The labs in this workshop provide a basic, hands-on introduction to DSS through JavaScript, the default scripting language for DSS. You may also be interested in [this User's Guide for DSS](https://software-dl.ti.com/ccs/esd/documents/users_guide/sdto_dss_handbook.html).
The first lab will cover how to create and run a simple DSS script. The second lab will demonstrate how to debug scripts using the Rhino Debugger. The third lab will show how to catch and handle exceptions within a DSS script. The final lab will cover how to use the scripting console in CCS, and how to set breakpoints from a script.
### API Documentation
The Debug Server API documentation is included in the installation of the desktop version of Code Composer Studio. To view this documentation, open the following file and click on the **DS API Documentation** link (<CCS_INSTALL_DIR> is the location of CCS on your machine, for example, for CCS 8 on Windows it might be <tt>C:/ti/ccsv8/</tt>).
<tt><CCS_INSTALL_DIR>/ccs_base/scripting/docs/GettingStarted.html</tt>
In the upper-left corner of the screen are the packages. Below that is the list of classes. To the right is the main window showing a description of the class along with a list of fields and methods. You are encouraged to consult the documentation for all classes and APIs used in the labs.
Lab Prerequisites
---------------
### Requirements
The following are required to complete the workshop:
* [Code Composer Studio (CCS)](https://processors.wiki.ti.com/index.php/Download_CCS) (preferably version 8 or later)
* SimpleLink CC1352R1 LaunchPad and a USB cable
* the [<tt>DSS-Workshop</tt>](./files/DSS-Workshop.zip) folder
<!-- TODO: make a link! -->
Make note of the location of the CCS installation and of the <tt>DSS-Workshop</tt> folder on your machine. By default, the labs will assume they are placed in <tt>C:/ti/</tt> and <tt>C:/CCS-Workshops/</tt> respectively.
### Setup
The following steps are basic setup common to all labs. The same Command Prompt window can be used for more than one of these labs without the need to go through this setup again.
1. For simplicity, make sure that the LaunchPad being used for this workshop is the only board connected to your computer.
2. Open a Command Prompt or Terminal window and change directory to the <tt>DSS-Workshop</tt> folder. The default location used by this workshop is <tt>C:/CCS-Workshops/</tt>.
3. Run the <tt>setpath.bat</tt> file and provide the path to your CCS installation as an argument (for example <tt>C:/ti/ccsv8</tt>). Use quotes around the path to avoid problems with spaces.
For example:
```text
> setpath "C:/ti/ccsv9/"
```
[[+y OS X and Linux users (expand)
Instead of using <tt>setpath.bat</tt>, type the following command into your terminal (making appropriate substitutions):
```text
PATH="$PATH:<CCS_INSTALL_PATH>/ccsv<RELEASE_#>/ccs_base/scripting/bin"
```
This will ensure that the <tt>dss.sh</tt> script is in your path. +]]
Your environment is now ready for the labs in this workshop.
### Brief Introduction to JavaScript
To ensure the reader is familiar with basic [JavaScript syntax](https://www.w3schools.com/js/js_syntax.asp), this quick overview is provided. The syntax shown will be more than sufficient for the purposes of this workshop.
```javascript
// Comments are like C and Java
/* This is also a JavaScript comment */
// Semi-colons are used to end statements (like C and Java)
x = 1;
// Variables are dynamically typed and are declared with a `var` statement
var x;
var y = "y";
// Strings are concatenated using the `+` operator
print("He" + "llo"); // prints Hello in the console
// Control statements are similar to C and Java
// if, else, switch, for, while, etc.
if (condition) {
doSomething();
}
// Functions can be defined with the `function` keyword
function foo(x) {
y = x;
}
// Call methods via <object>.<method>
myObject.objectMethod(myArgument);
```
Lab 1 — Creating and Running a Basic DSS Script
--------------
In this lab, you will create a basic DSS JavaScript script that will load and run a sample program (<tt>blinky20.out</tt>) on a SimpleLink CC1352R1 LaunchPad. You will then run the script from the command line and observe the results. The lab will give a brief description of the objects and methods used, full descriptions can be found in the [documentation](#api-documentation).
### Creating the Script
1. Create a new file in your favorite text editor and save it as <tt>lab1.js</tt> in the <tt>DSS-Workshop/lab1</tt> directory. This is the file in which we will create the script for this lab.
{{b The CCS Editor supports syntax highlighting for JavaScript files.}}
2. Use the `importPackage()` JavaScript API to import the relevant packages for the script.
```javascript
importPackage(Packages.com.ti.debug.engine.scripting);
importPackage(Packages.com.ti.ccstudio.scripting.environment);
importPackage(Packages.java.lang);
```
3. Create some variables for the various files we will be using. You will need to modify the first few variables to match your environment. To avoid issues, use full paths with forward slashes.
```javascript
// Modify the following two variables to match your environment. Use forward slashes and full paths.
// (non-windows users: instead of ~/ use the full path to your home folder)
// The first variable should match the argument passed to setpath.bat
// The second should be the path for the DSS-Workshop folder
var ccsInstallDir = "C:/ti/ccsv8/";
var dssWorkshopDir = "C:/CCS-Workshops/DSS-Workshop/";
// The necessary files
var logFile = dssWorkshopDir + "/lab1/log.xml";
var logFileStylesheet = ccsInstallDir + "/ccs_base/scripting/examples/DebugServerExamples/DefaultStylesheet.xsl";
var deviceCCXMLFile = dssWorkshopDir + "/target-config/CC1352R1F3.ccxml";
var programToLoad = dssWorkshopDir + "/lab1/blinky20.out";
```
4. Get a handle to the `ScriptingEnvironment` object
```javascript
var scriptEnv = ScriptingEnvironment.instance();
```
{{b The `ScriptingEnvironment` object is the main entry point into the DSS session and the factory for creating other scriptable servers and sessions.}}
5. Enable and Configure Logging
Use the `traceBegin()` API to enable DSS logging to the file specified by the `logFile` variable.
```javascript
scriptEnv.traceBegin(logFile, logFileStylesheet);
```
{{b DSS log files are in XML format which can be styled using XSLT (XML Stylesheet Transforms). We use the example <tt>DefaultStylesheet.xsl</tt> file provided in the scripting examples folder of the CCS installation. To view the styled log files, it is recommended to use Internet Explorer for the best compatibility. More details on DSS logging can be found [here](https://software-dl.ti.com/ccs/esd/documents/users_guide/sdto_dss_handbook.html#logging).}}
6. Set the verbosity level for the console and the log file using the `traceSetConsoleLevel()` and `traceSetFileLevel()` APIs.
```javascript
scriptEnv.traceSetConsoleLevel(TraceLevel.INFO);
scriptEnv.traceSetFileLevel(TraceLevel.ALL);
```
{{b The following form a subset of the trace levels available. They are listed from least to most verbose (each level contains all messages from the levels above it):
- `TraceLevel.OFF` (turn off logging)
- `TraceLevel.SEVERE` (only very severe messages from the debugger)
- `TraceLevel.WARNING` (adds warning messages from the debugger)
- `TraceLevel.INFO` (adds basic messages and C I/O)
- `TraceLevel.ALL` (log everything)
For more details and a full list of trace levels, see the [documentation](#api-documentation) for `TraceLevel` class.}}
7. Use the `getServer()` API to open a connection to the debugger (DebugServer.1).
```javascript
var debugServer = scriptEnv.getServer("DebugServer.1");
```
{{b The `DebugServer` object returned is the main handle for the debugger. This object is used to configure the debugger and start debug sessions for targets.}}
8. Configure the debugger for the desired target board by passing the target configuration **\*.ccxml** file to the debug server with the `setConfig()` API.
```javascript
debugServer.setConfig(deviceCCXMLFile);
```
9. Open a debug session for the Cortex M4 processor on the LaunchPad with the `openSession()` API.
```javascript
var debugSession = debugServer.openSession("*", "Cortex_M4_0");
```
{{b The `DebugSession` object returns the main handle for the debug session that was started. All the debugging operations for the target can be accessed using this object.}}
[[b Multiple configured targets
Some boards, such as the CC1352R1 LaunchPad, have multiple debuggable objects (CPUs). By providing the arguments `"*", "Cortex_M4_0"` a debug session will be opened to the Cortex M4 CPU on the first configured connection (board). To avoid potential issues, we ask that you ensure only one board is connected to your machine while completing these labs.
To learn more about specifying a target for a debug session, see the [documentation](#api-documentation) for `DebugServer.openSession()`.]]
10. Connect to the target using the `connect()` API of the debug session's `target` field.
```javascript
debugSession.target.connect();
```
{{b The `Target` class supports methods for target execution (`run`, `halt`, `restart`), stepping, and connecting/disconnecting from the target.}}
11. Load the program (in this case <tt>blinky20.out</tt>) into memory.
```javascript
debugSession.memory.loadProgram(programToLoad);
```
{{b The `Memory` class supports methods for memory access such as `save`, `load`, `read`, `write`, register access, and program loading.}}
12. Issue a command to the target to run the loaded program.
```javascript
debugSession.target.run();
```
{{b `run()` does not return control until the target has been halted. In this case, it will return control once the target reaches the end of the program.}}
13. Shutdown the debugger with the debug server's `stop()` API.
```javascript
debugServer.stop();
```
{{b This call closes both closes the debug session and shuts down the debug server (basically terminates the debugger).}}
14. End the log file tracing and disable logging with the scripting environment's `traceEnd()` API.
```javascript
scriptEnv.traceEnd();
```
{{b This is recommended to properly close the log file.}}
15. Save the file as <tt>lab1.js</tt> in the <tt>lab1</tt> subfolder if you have not already done so.
[[+d The final script should look like this (expand)
[[r Note:
Some optional `traceWrite` calls were added to give some feedback in the console.]]
```javascript
// Import the DSS Packages into our namespace to save ourselves some typing
importPackage(Packages.com.ti.debug.engine.scripting);
importPackage(Packages.com.ti.ccstudio.scripting.environment);
importPackage(Packages.java.lang);
// Modify the following two variables to match your environment. Use forward slashes and full paths.
// (non-windows users: instead of ~/ use the full path to your home folder)
// The first variable should match the argument passed to setpath.bat
// The second should be the path for the DSS-Workshop folder
var ccsInstallDir = "C:/ti/ccsv8/";
var dssWorkshopDir = "C:/CCS-Workshops/DSS-Workshop/";
// The necessary files
var logFile = dssWorkshopDir + "/lab1/log.xml";
var logFileStylesheet = ccsInstallDir + "/ccs_base/scripting/examples/DebugServerExamples/DefaultStylesheet.xsl";
var deviceCCXMLFile = dssWorkshopDir + "/target-config/CC1352R1F3.ccxml";
var programToLoad = dssWorkshopDir + "/lab1/blinky20.out";
// Get a handle to the scripting environment object
var scriptEnv = ScriptingEnvironment.instance();
// Create a log file to log script execution
scriptEnv.traceBegin(logFile, logFileStylesheet);
// Set the trace verbosity levels for the console and the logs
scriptEnv.traceSetConsoleLevel(TraceLevel.INFO);
scriptEnv.traceSetFileLevel(TraceLevel.ALL);
// Optional
scriptEnv.traceWrite("Begin scripting session");
// Get a handle to a ScriptServer object to interact with the debugger
var debugServer = scriptEnv.getServer("DebugServer.1");
// Set the target configuration
debugServer.setConfig(deviceCCXMLFile);
// Open a debug session with the first configured target
var debugSession = debugServer.openSession("*", "Cortex_M4_0");
// Connect to the target
debugSession.target.connect();
// Load our program
debugSession.memory.loadProgram(programToLoad);
// Run the target
debugSession.target.run();
// Target has finished running, terminate the debugger
debugServer.stop();
// Optional
scriptEnv.traceWrite("End scripting session");
// Stop logging and exit
scriptEnv.traceEnd();
```
+]]
### Running the Script
1. If you have not already done so, open a Command Prompt or Terminal window and setup your environment as described in the [setup section](#setup).
2. Change directory to the <tt>DSS-Workshop/lab1/</tt> folder.
3. Run the script
```text
> dss lab1.js
```
[[+y "dss: command not found" on OS X or Linux? (expand)
It is possible that the dss script does not have execute permission. Try the following instead:
```text
> dss.sh lab1.js
```
If problems persist, make sure that the `ccs_base/scripting/bin/` subfolder of the CCS installation is in your path (see [setup](#setup)).
+]]
The script will run and the the LED on the LaunchPad will blink 20 times before terminating. If you included the optional `traceWrite` calls shown in the final script above, your console should look something like this:
```text
C:\CCS-Workshops\DSS-Workshop\lab1>dss lab1.js
Begin scripting session
Cortex_M4_0: GEL Output: Board Reset Complete.
End scripting session
```
[[b Note
The lines reading `Begin scripting session` and `End scripting session` were added using `scriptEnv.traceWrite()`, to make it clear when the script is running. See the final script given above for details.
]]
4. Open the generated log file <tt>lab1/log.xml</tt> in a web browser (Internet Explorer is recommended for compatibility). If the default XML stylesheet was correctly used, it should look like the image below:
Notice that the log file has much more information than what was output to the console, including sequence numbers, timing information, and status messages (due to having selected a more verbose trace level).
Lab 2 — Using the Rhino Debugger
--------------
In this lab you will debug and fix a broken DSS script using the [Rhino Debugger](https://www.mozilla.org/rhino/debugger.html).
### Run the provided example script
1. Open the provided example script <tt>lab2a.js</tt> in the <tt>lab2</tt> subfolder with a text editor and modify the top two variables to match your installation. Save the file.
2. If you have not already done so, open a Command Prompt or Terminal window and setup your environment as described in the [setup section](#setup).
3. Change directory to the <tt>lab2</tt> subfolder and run the provided example script.
```text
> dss lab2a.js
```
The script will start a debug session for the LaunchPad and attempt to load and run the provided "Hello World" example program, but will fail with errors.
```text
C:\CCS-Workshops\DSS-Workshop\lab2>dss lab2a.js
Begin scripting session
SEVERE: Cannot perform operation, target is not connected.
SEVERE: Error loading "C:/CCS-Workshops/DSS-Workshop//lab2/hello.out": Cannot perform operation, target is not connected.
org.mozilla.javascript.WrappedException: Wrapped com.ti.ccstudio.scripting.environment.ScriptingException: Error loading "C:/CCS-Workshops/DSS-Workshop//lab2/hello.out": Cannot perform operation, target is not connected. (lab2a.js#50)
at org.mozilla.javascript.Context.throwAsScriptRuntimeEx(Context.java:1693)
at org.mozilla.javascript.MemberBox.invoke(MemberBox.java:160)
at org.mozilla.javascript.NativeJavaMethod.call(NativeJavaMethod.java:204)
at org.mozilla.javascript.optimizer.OptRuntime.call1(OptRuntime.java:66)
at org.mozilla.javascript.gen.c1._c0(lab2a.js:50)
at org.mozilla.javascript.gen.c1.call(lab2a.js)
at org.mozilla.javascript.ContextFactory.doTopCall(ContextFactory.java:340)
at org.mozilla.javascript.ScriptRuntime.doTopCall(ScriptRuntime.java:2758)
at org.mozilla.javascript.gen.c1.call(lab2a.js)
at org.mozilla.javascript.gen.c1.exec(lab2a.js)
at org.mozilla.javascript.tools.shell.Main.evaluateScript(Main.java:503)
at org.mozilla.javascript.tools.shell.Main.processFileSecure(Main.java:425)
at org.mozilla.javascript.tools.shell.Main.processFile(Main.java:391)
at org.mozilla.javascript.tools.shell.Main.processSource(Main.java:382)
at org.mozilla.javascript.tools.shell.Main.processFiles(Main.java:179)
at org.mozilla.javascript.tools.shell.Main$IProxy.run(Main.java:100)
at org.mozilla.javascript.Context.call(Context.java:528)
at org.mozilla.javascript.ContextFactory.call(ContextFactory.java:450)
at org.mozilla.javascript.tools.shell.Main.exec(Main.java:162)
at com.ti.ccstudio.apps.internal.scripting.RunScript$1.run(RunScript.java:89)
Caused by: com.ti.ccstudio.scripting.environment.ScriptingException: Error loading "C:/CCS-Workshops/DSS-Workshop//lab2/hello.out": Cannot perform operation, target is not connected.
at com.ti.debug.engine.scripting.Memory.loadProgram(Memory.java:932)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
at java.lang.reflect.Method.invoke(Method.java:498)
at org.mozilla.javascript.MemberBox.invoke(MemberBox.java:145)
... 18 more
```
The error messages indicates that the program load failed because we were not connected to the target. The same error messages can be found at the end the log file <tt>lab2/log.xml</tt>.
This is odd since a call to `target.connect()` is present on line 46 of <tt>lab2a.js</tt>.
{{r You may have already spotted the bug in the script, but don't fix it yet. The purpose is to showcase using the Rhino Debugger to debug the script.}}
### The Rhino Debugger
1. Run the example script within the Rhino Debugger by passing the `-dss.debug` flag to the dss script.
```text
> dss -dss.debug lab2.js
```
The script will be executed by the debugger and halted at the start of the script.
2. Use the **Step Over** button to step through the script and see if `target.connect()` is ever called.
Notice that `target.connect()` is never reached due to a bug in the if-statement which precedes it.
```javascript
// Check to see if the target is already connected
// target.isConnected() API will return 'true' if it is connected
if (debugSession.target.isConnected())
{
// Connect to the target
debugSession.target.connect();
}
```
The `target.isConnected()` API will return true if the target is connected and false otherwise. The intent is to check if the target is already connected and only connect if this is not the case. Therefore the condition in the if-statement should be negated.
```javascript
if (!debugSession.target.isConnected())
```
3. Close the Rhino Debugger window. Use a text editor to modify the offending if-statement so that `target.connect()` is called when the target is not yet connected. Save the resulting file as <tt>lab2b.js</tt> in the <tt>lab2</tt> subfolder.
4. Run the modified script from the Command Prompt or Terminal. The script should run successfully and you should see the following output:
```text
C:\CCS-Workshops\DSS-Workshop\lab2>dss lab2b.js
Begin scripting session
Cortex_M4_0: GEL Output: Board Reset Complete.
Hello World!
End scripting session
```
More details regarding the Rhino Debugger can be found [here](https://software-dl.ti.com/ccs/esd/documents/users_guide/sdto_dss_handbook.html#debugging-your-javascript).
Lab 3 — Catching Exceptions
--------------
In this lab, you will modify an example script to catch and handle DSS API exceptions.
1. Open the provided example script <tt>lab3a.js</tt> file in the <tt>lab3</tt> folder and modify the top two variables to match your installation. Save the file.
2. If you have not already done so, open a Command Prompt or Terminal window and setup your environment as described in the [setup section](#setup).
3. Change directory to the <tt>lab3</tt> subfolder and run the provided example script.
```text
> dss lab3a.js
```
The script will start a debug session for the LaunchPad and attempt to load and run an example program (<tt>modem.out</tt>) but will fail with errors.
```text
C:\CCS-Workshops\DSS-Workshop\lab3>dss lab3a.js
Begin scripting session
Cortex_M4_0: GEL Output: Board Reset Complete.
SEVERE: Cortex_M4_0: GEL: File: C:/CCS-Workshops/DSS-Workshop//lab3/modem.out Does not match the target type, not loaded.
SEVERE: File: C:/CCS-Workshops/DSS-Workshop//lab3/modem.out
Does not match the target type, not loaded.
SEVERE: Error loading "C:/CCS-Workshops/DSS-Workshop//lab3/modem.out": File: C:/CCS-Workshops/DSS-Workshop//lab3/modem.out
Does not match the target type, not loaded.
org.mozilla.javascript.WrappedException: Wrapped com.ti.ccstudio.scripting.environment.ScriptingException: Error loading "C:/CCS-Workshops/DSS-Workshop//lab3/modem.out": File: C:/CCS-Workshops/DSS-Workshop//lab3/modem.out
Does not match the target type, not loaded. (lab3a.js#45)
at org.mozilla.javascript.Context.throwAsScriptRuntimeEx(Context.java:1693)
at org.mozilla.javascript.MemberBox.invoke(MemberBox.java:160)
at org.mozilla.javascript.NativeJavaMethod.call(NativeJavaMethod.java:204)
at org.mozilla.javascript.optimizer.OptRuntime.call1(OptRuntime.java:66)
at org.mozilla.javascript.gen.c1._c0(lab3a.js:45)
at org.mozilla.javascript.gen.c1.call(lab3a.js)
at org.mozilla.javascript.ContextFactory.doTopCall(ContextFactory.java:340)
at org.mozilla.javascript.ScriptRuntime.doTopCall(ScriptRuntime.java:2758)
at org.mozilla.javascript.gen.c1.call(lab3a.js)
at org.mozilla.javascript.gen.c1.exec(lab3a.js)
at org.mozilla.javascript.tools.shell.Main.evaluateScript(Main.java:503)
at org.mozilla.javascript.tools.shell.Main.processFileSecure(Main.java:425)
at org.mozilla.javascript.tools.shell.Main.processFile(Main.java:391)
at org.mozilla.javascript.tools.shell.Main.processSource(Main.java:382)
at org.mozilla.javascript.tools.shell.Main.processFiles(Main.java:179)
at org.mozilla.javascript.tools.shell.Main$IProxy.run(Main.java:100)
at org.mozilla.javascript.Context.call(Context.java:528)
at org.mozilla.javascript.ContextFactory.call(ContextFactory.java:450)
at org.mozilla.javascript.tools.shell.Main.exec(Main.java:162)
at com.ti.ccstudio.apps.internal.scripting.RunScript$1.run(RunScript.java:89)
Caused by: com.ti.ccstudio.scripting.environment.ScriptingException: Error loading "C:/CCS-Workshops/DSS-Workshop//lab3/modem.out": File: C:/CCS-Workshops/DSS-Workshop//lab3/modem.out
Does not match the target type, not loaded.
at com.ti.debug.engine.scripting.Memory.loadProgram(Memory.java:932)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
at java.lang.reflect.Method.invoke(Method.java:498)
at org.mozilla.javascript.MemberBox.invoke(MemberBox.java:145)
... 18 more
```
The error message indicates that the <tt>modem.out</tt> program was not built for a Cortex M4 processor like the one on our LaunchPad.
{{b The Debug Server APIs throw Java exceptions. You can handle the exceptions in the script to fail gracefully or continue on (see [JavaScript's Try-Catch-Throw-Finally](https://www.w3schools.com/js/js_errors.asp)).}}
4. Modify the script to catch the exceptions thrown by `memory.loadProgram()` and terminate the script gracefully.
```javascript
try {
debugSession.memory.loadProgram(programToLoad);
} catch (ex) {
scriptEnv.traceWrite("Program load of " + programToLoad + " failed!\nTerminating script.");
quit();
}
```
{{b The JavaScript `quit()` call will gracefully terminate the JavaScript session.}}
5. Save the modified script as <tt>lab3b.js</tt> in the <tt>lab3</tt> subfolder.
6. Run the modified script from the Command Prompt or Terminal. The script should run successfully and your console should look like this:
```text
C:\CCS-Workshops\DSS-Workshop\lab3>dss lab3b.js
Begin scripting session
Cortex_M4_0: GEL Output: Board Reset Complete.
SEVERE: Cortex_M4_0: GEL: File: C:/CCS-Workshops/DSS-Workshop//lab3/modem.out Does not match the target type, not loaded.
SEVERE: File: C:/CCS-Workshops/DSS-Workshop//lab3/modem.out
Does not match the target type, not loaded.
SEVERE: Error loading "C:/CCS-Workshops/DSS-Workshop//lab3/modem.out": File: C:/CCS-Workshops/DSS-Workshop//lab3/modem.out
Does not match the target type, not loaded.
Program load of C:/CCS-Workshops/DSS-Workshop//lab3/modem.out failed!
Terminating script.
```
Lab 4 — The Scripting Console and Breakpoints
---------------
In this lab, you will be introduced to the Scripting Console in CCS and learn how to run DSS scripts from the Scripting Console. You will also learn how to set breakpoints from within a DSS script.
{{b Code Composer Studio's Scripting Console provides interactive scripting support. Debug Server APIs can be called from the console and full DSS scripts can be run. More details can be found [here](https://software-dl.ti.com/ccs/esd/documents/ccsv7_scripting_console.html).}}
### The Scripting Console
1. Open Code Composer Studio and chose the following location as the workspace folder:
```text
<DSS_WORKSHOP_INSTALL_DIR>/DSS-Workshop/lab4/workspace/
```
You may close the *Getting Started* page.
2. Open the Scripting Console by selecting **View** > **Scripting Console** from the menu bar. By default, the Scripting Console will open somewhere near the bottom of the perspective.
3. Press TAB for a list of supported commands. (Agree to display all possibilities.)
4. Use `help` to get the help entry for a command. For example, typing `help loadJSFile` shows the following:
```text
js:> help loadJSFile
Description: Load a JavaScript file or all the JavaScript files in the directory. Example: loadJSFile c:\myDirectory\myJavaScript.js
Syntax: loadJSFile(file,store)
Arguments:
file - the JavaScript file or a directory.
store - [optional] true, store the file(s) to the preference, the script will auto reload the next time the view is open.
```
### Running a Script From the Scripting Console
Run the DSS script created in lab 1 from the Scripting Console (the full script can be found at the end of the [Creating the Script section](#Creating-the-Script)). Replace <tt>C:/CCSWorkshops/</tt> with the path to the <tt>DSS-Workshop</tt> folder on your machine.
```text
js:> loadJSFile(C:/CCS-Workshops/DSS-Workshop/lab1/lab1.js)
```
[[y Check your paths
If you encounter errors, make sure that all paths used in the Scripting Console and in the <tt>lab1.js</tt> script are correct, full paths that use forward slashes.]]
The script will be executed and the following can be observed:
1. CCS will switch to the *CCS Debug* perspective as a debug session is launched.
Script actions will be visible in the GUI, but actions might execute too quickly to be readable.
2. The LED on the LaunchPad will blink 20 times as the program is run.
3. CCS will switch to the *CCS Edit* perspective when the script terminates the debug session.
### Setting a Breakpoint
1. Run the (fixed) script from lab 2 (<tt>lab2b.js</tt>) from the Scripting Console as done [above](#running-a-script-from-the-scripting-console).
```text
js:> loadJSFile(C:/CCS-Workshops/DSS-Workshop/lab2/lab2b.js)
```
Everything should proceed as it did when running the script from lab 1, except that instead of the LED blinking 20 times, the text "Hello World!" will be printed to the C I/O console (this may happen too quickly to see).
2. Switch back to the *CCS Debug* perspective (**Window** > **Open Perspective** > **CCS Debug**) and confirm that "Hello World!" was correctly outputted to the C I/O console.
3. Open the <tt>hello.c</tt> source file, located in the <tt>lab2</tt> subfolder, in a text editor. Take note of the line number for the line
```C
printf("Hello World!\n");
```
(The line number should be 7.)
4. Open the script <tt>lab2b.js</tt> from lab 2 and use the `breakpoint.add()` API to set a breakpoint after the program is loaded.
```javascript
...
// Load a program
debugSession.memory.loadProgram(programToLoad);
// Add a breakpoint at the printf() statement
debugSession.breakpoint.add("hello.c", 7);
// Run the target
debugSession.target.run();
// All done
debugServer.stop();
...
```
{{b To learn more about the use of breakpoints in DSS see [this link](https://software-dl.ti.com/ccs/esd/documents/users_guide/sdto_dss_handbook.html#breakpoints) or the [documentation](#api-documentation) for the `Breakpoint` class }}
5. Remove the `DebugServer.stop()` call to stop/terminate the debugger. The debug session should remain open after hitting the breakpoint.
```javascript
...
// Run the target
debugSession.target.run();
// All done
// debugServer.stop(); Removed
...
```
{{b `target.run()` returns control when the target has been halted. This will first occur when the breakpoint is reached (in the previous examples, this only happened upon reaching the end of the program). Thus, this new script should not end the debug session upon regaining control.}}
6. Save the resulting script as <tt>lab4.js</tt> in the <tt>lab4</tt> subfolder.
7. Run the <tt>lab4.js</tt> script form the Scripting Console.
```text
js:> loadJSFile(C:/CCS-Workshops/DSS-Workshop/lab4/lab4.js)
```
CCS will switch to the *CCS Debug* perspective, the target will halt at the location of the breakpoint we set, and the script will exit without terminating the debug session.
[[y CCS cannot find the source?
CCS may not be able to find the source file <tt>hello.c</tt> as the executable was built with the source files in a different directory. Use the **Locate File...** button to direct CCS to the folder containing <tt>hello.c</tt> (it can be found in the <tt>lab2</tt> subdirectory).]]
8. CCS displays the source file with execution stopped at the breakpoint we set at the `printf()` statement.
9. Single step over (F6) the `printf()` statement to continue the debugging of the application. Notice that the text "Hello World!" appears in the C I/O console window.
10. You may now terminate the debugger in CCS (Ctrl+F2).
Summary
---------------
You should now be familiar with the basics of Debug Server Scripting. The first lab covered how to create and run a simple DSS script. The second lab demonstrated how to debug scripts using the Rhino Debugger. The following lab showed how to catch and handle exceptions. The final lab covered both the use of the Scripting Console in CCS and how to set breakpoints in DSS scripts. This concludes the DSS Fundamentals Workshop. For further details see [this User's Guide for DSS](https://software-dl.ti.com/ccs/esd/documents/users_guide/sdto_dss_handbook.html) or the [API documentation](#api-documentation).
<!-- End of markdown source -->
<div id="footer"></div>
]]>