Overview

The Scripting Console is a tool in Code Composer Studio which allows users to specify commands to the IDE through a console. It is a JavaScript shell which will create a Debug Server Scripting (DSS) Scripting Environment instance when it is opened. This allows users to call DSS APIs from the console. Full DSS scripts can also be run straight from the console.

Launching

To launch the Scripting Console, use the View → Scripting Console menu option.

Available Actions

The following actions are available in the Scripting Console View's toolbar.

Icon	Name	Description
	Clear Console View	Clear the content of the scripting console view, this action is the same as the `cls` command.
	Load Command or JavaScript file	Load a Command or JavaScript file from disk and execute it immediately. This action is similar to the `execCmdFile` or `loadJSFile` commands (for Command and JavaScript files respectively). See the dedicated section for more details.
	Pin Active Debug Session	Pin the debug server scripting commands to the active debug session that you have selected in the Debug View; it is useful for multiple CPU debug session.
	View Menu	Select the command group(s) that you want to see when pressing TAB key in the scripting console view. See the command groups section for more details.

The Scripting Console also supports basic copy and paste functionality.

Commands

The Scripting Console supports a set of built-in console commands for more commonly used functionality. These console commands are JavaScript functions contained in JavaScript files automatically loaded by the Scripting Console when opened. Most of these JavaScript functions simply wrap DSS calls underneath to make it easier to automate actions with a single short command.

The TAB key can be used to display a full list of the loaded console commands. It can also be used to suggest completions for partially typed commands. Command specific documentation for a command can be obtained by typing help <command> or <command> /?.

Syntax

The following is recommended syntax for calling commands in the Scripting Console. Some commands also accept other syntax (such as adding spaces between arguments or omitting parentheses).

When calling a command, arguments should be separated by a comma and no spaces. There can be a space between the command name and the list of arguments. For example:
```
js:> commandName(arg1,arg2,arg3)
```
When passing a reference to a file, use double quotes and C-syntax parameters, including escaping special characters.
```
js:> ds.setConfig("C:/ti/target_config/CC1352F1R3.ccxml")
js:> ds.setConfig("C:\\ti\\target_config\\CC1352F1R3.ccxml")
```
The boolean constants true and false must in lowercase.

Version Control and Project Names

If using version control, the name of a project with changes must be preceded by the > signal. For example:

js:> buildProject("> myProject")

The Eval Command

The Scripting Console has its own eval command which evaluates C expressions and GEL commands to an integer result. This command differs from the standard JavaScript eval function. Any JavaScript being executed from the Scripting Console using the JavaScript eval will be impacted since the console eval function will override the standard JavaScript function. For more details see this link and the Debug Server documentation for Expression.evaluate().

Command Groups

There are many commands available in the Scripting Console. This can lead to a large number of suggestions when hitting the TAB key. Commands are divide into groups to allow you to filter the commands suggested when hitting TAB. You can access the filter settings in the Scripting Console's View Menu.

Analysis UI Scripting Commands: Set of commands that provide data visualization and analysis tools.
Debug Server Commands: Set of debug server commands that use the debug server scripting (DSS) api. These commands will interact with the current debug context in the workbench window, unless you have the active session pinned using the toolbar action.
GUI Commands: Set of commands which return number formats used by the Expressions View.
Hot Menu Commands: Set of commands that interact with the Scripts hotmenu. To learn more about the Scripts menu, see the Scripts menu section.
Scripting Console Commands: Set of basic commands that interact with the console itself such as cls, help, print, services, loadJSFile.
UI Scripting Commands: Set of UI specific commands that interact with the user interface, such as cleanProject and openView. These commands will execute in the current workbench window context. If you have more than one workbench window open, it won't affect the other workbench window.
Unspecified: Set of commands that don't have any associated group (or service). The group is provided as part of the function documentation of a JavaScript file.

Loading Command and JavaScript Files

The Scripting Console allows commands to be loaded from files and executed. Two kinds of files can be loaded: command (*.cmd) files, and JavaScript (*.js) files. The files are loaded with the execCmdFile and loadJSFile commands respectively. The files can also be loaded using the Scripting Console View's Load Scripting Console Command File or JavaScript File button (Open folder icon) , which will call the appropriate command.

A command file is simply a file in which each line is a command to be executed, verbatim, in the Scripting Console. The execCmdFile command executes the commands recorded in the *.cmd file in succession, as if each was typed. On the other hand, since the Scripting Console is a JavaScript shell, JavaScript files can also be used to automate most of the console's functionality. The loadJSfile command is used to load and execute a JavaScript file.

The advantage of using a JavaScript file over a command file is that functions, loops, if statements, comments, etc. can span more than one line. On the other hand, while most of the Scripting Console's commands are JavaScript functions, there are a few commands for which this is not the case. This means that a JavaScript file cannot make use of these commands. For example, the commands in the Scripting Console Commands group, with the exception of the print command, are not available from within a JavaScript file.

Examples

Loading and saving memory

Memory and program load operations such as loadRaw, loadData, loadProg have the basic syntax below.

    loadRaw(0x80000000,PAGE_PROGRAM,"C:\\temp\\myFile.bin",32,false)
    loadRaw(0x80000000,0,"/temp/myFile.bin",32,true)

Do not insert spaces between the commas and the parameters inside the parenthesis
When passing a reference to a file, use double quotes and use C-syntax parameters, including escaping special characters
Boolean values must be passed with the constants false and true these must be in lowercase.
The constants that designate the memory page of the target are optional: PAGE_PROGRAM, PAGE_DATA and PAGE_IO can be replaced with 0, 1 and 2 respectively.

Memory save operations are slightly different

    saveRaw(PAGE_PROGRAM,0x80000000,"C:\\temp\\myFile.bin",0x400,32,false)

The forward slash syntax for the filename designator does not work in this case.
The length parameter (0x400 in this example) specifies the total number of elements to be read, which is dependent on the target device. For MSP430, F28x and C55x each element consists of 16 bits or two bytes (in the example above 0x800 bytes will be read). For all other architectures it is 32 bits or four bytes (0x1000 bytes for the example above).

Project Build

To build a project the project must exist in the current workspace.

    buildProject("myProject")
    buildProject "myProject"

The return value is always true, regardless of the success of the build.
When using version control, projects with changes must be preceded with the ">" signal:
```
buildProject "> myProject"
```

Services

Within the Scripting Console, several services are available to be used from the console. A service is an entry point to a native Java scriptable object. Using the services command will echo a list of services to the console. Many are just used internally and not meant for public use. However, there are some that can be used publicly, such as:

ds: Similar to the DebugServer object that gets returned by the Scripting Environment's getServer("DebugServer.1") call.
env: Similar to the ScriptingEnvironment object that gets returned by the ScriptingEnvironment.instance() call.
hotmenu: Provides commands to add and remove GEL and JavaScript hotmenu items from the Scripts menu (see the dedicated section below).
activeDS: Provides access to methods for the current active debug session, similar to the DebugSession object returned by a call to the Debug Server's openSession() method. This service does not show up when using the services command, and only exists when a debug session is active.

These services can be used with DSS APIs from the console. For example you could use APIs to create a Scripting Environment and Debug Server:

js:> script = ScriptingEnvironment.instance();

js:> script.traceBegin("dssLog.xml");

js:> debugServer = script.getServer("DebugServer.1");

js:> debugServer.setConfig("CC1352R1F3.ccxml");

js:> debugSession = debugServer.openSession("*", "Cortex_M4_0");

js:> debugSession.memory.loadProgram("myApp.out");

js:> debugSession.target.run();

Or instead you can leverage the existing services for the Scripting Environment (env) and Debug Server (ds):

js:> env.traceBegin("dssLog.xml");

js:> ds.setConfig("CC1352R1F3.ccxml");

js:> debugSession = ds.openSession("*", "Cortex_M4_0");

js:> debugSession.memory.loadProgram("myApp.out");

js:> debugSession.target.run();

Note that activeDS could have been used instead of the debugSession identifier. These services can also be reused in DSS JavaScript files that are meant to be run from the Scripting Console (such as custom console commands).

Note

If using these services in a JavaScript file, they will not be recognized when running the script outside the Scripting Console. Furthermore, the activeDS service will not be recognized when you are not in an active debug session.

Running DSS Scripts

The loadJSFile console command can be used to load and run standalone DSS JavaScript files from the Scripting Console.

js:> loadJSFile("C:/ti/exampleDssScript.js")

The standalone DSS JavaScript's call to create the scripting environment will attach to the existing scripting environment created by the Scripting Console. If desired, the script can be modified to check if it is running from within the Scripting Console, and leverage the existing services such as env, ds, and so forth, if it is:

var ds;

// Check to see if running from within the Scripting Console
var withinCCS = (ds !== undefined);

// Create scripting environment and get debug server if running standalone
if (!withinCCS)
{
    // Import the DSS packages into our namespace to save on typing
    importPackage(Packages.com.ti.debug.engine.scripting);
    importPackage(Packages.com.ti.ccstudio.scripting.environment);
    importPackage(Packages.java.lang);

    // Create our scripting environment object - which is the main entry point into any script and
    // the factory for creating other Scriptable servers and Sessions
    var script = ScriptingEnvironment.instance();

    // Get the Debug Server and start a Debug Session
    var debugServer = script.getServer("DebugServer.1");
}
else // otherwise leverage existing scripting environment and debug server
{
    var debugServer = ds;
    var script = env;
}

Your script can also be modified to check if it is being run from the scripting console while a debug session is active (by checking for activeDS) and use the current active debug session instead of trying to open a new one.

Custom Console Commands

In addition to the built-in console commands, the Scripting Console allows for the creation of custom commands which can automate any of its normal functionality. The commands can be called from the console or added to a 'hotmenu' in the menu bar for easy access outside the console.

Creating Custom Commands

To create a custom command, create a new JavaScript file with a function for the new console command. The body of the function can contain whatever actions you wish the new console command to execute. You can provide documentation for your functions with a JavaDoc like syntax, the information will be shown when you execute the help command for the specified function.

/**
 * Read multiple words (of the default word-size) from the target and return the result as an array of integers.
 * @param address the starting.
 * @param page a one-digit number that identifies the type of memory: 0 - Program, 1 - Data, 2 - I/O
 * @param numWords number of words to read.
 * @param signed whether the returned words are signed or unsigned.
 * @return an array of target words.
 * @service DSS Debug Server Commands
 */
function readWord(address, page, numWords, signed) {
    return activeDS.memory.readWord(page, address, numWords, signed);
}

Once the file is competed and saved, use the loadJSFile console command to load the new JavaScript file. This will allow the function(s) to be called from the Scripting Console and the new custom command will appear in the list of console commands until the Scripting Console is restarted.

To have the new JavaScript file automatically loaded by the Scripting Console when it is launched, set the second argument for loadJSFile to true.

js:> loadJSFile("C:/ti/customCommand.js",true)

When creating custom console commands, it is suggested to reuse the services available from the Scripting Console when possible (see the dedicated services section).

The Scripts menu in the menu bar can be populated from the scripting console or from loaded JavaScript files. The items in the Scripts menu allow the execution of functions or scripts when they are clicked. Adding and removing items from the menu can be done using the hotmenu service. The hotmenu commands can be found in the Hot Menu Commands group, or by entering hotmenu and hitting TAB.

For example, loading the following the following JavaScript file adds a 'Connect to ...' submenu containing an item labeled 'SimpleLink CC1352'.

function connectToCC1352() {
    ds.setConfig("C:/ti/target_config/CC1352R1F3.ccxml");
    ds.openSession("*", "Cortex_M4_0").target.connect();
}

hotmenu.addJSFunction("Connect to .../SimpleLink CC1352", "connectToCC1352()");

Another example showing the use of the Scripts menu to execute a JavaScript function is shown in the quicktip video below: