< for more details.</td>
</tr>
<tr>
<td><img src="images/ccs_script_console_pintarget_button.gif" alt="Icon of a window with a pin in it"></td>
<td>Pin Active Debug Session</td>
<td>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.</td>
</tr>
<tr>
<td><img src="images/ccs_script_console_groupmenu_button.png" alt="Downward arrow icon"></td>
<td>View Menu</td>
<td>Select the command group(s) that you want to see when pressing TAB key in the scripting console view. See the <a href="#command-groups">command groups section</a> for more details.</td>
</tr>
</tbody>
</table>
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:
```javascript
js:> commandName(arg1,arg2,arg3)
```
* When passing a reference to a file, use double quotes and C-syntax parameters, including escaping special characters.
```javascript
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.
[[b Version Control and Project Names
If using version control, the name of a project with changes must be preceded by the `>` signal. For example:
```javascript
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](https://software-dl.ti.com/ccs/esd/documents/users_guide/sdto_dss_handbook.html#using-gel) 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 <img src="images/ccs_script_console_pintarget_button.gif" alt="Pin Target"> 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](#the-scripts-menu).
* **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 (<tt>\*.cmd</tt>) files, and JavaScript (<tt>\*.js</tt>) 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 <img src="images/ccs_script_console_loadfile_button.gif" alt="(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 <tt>\*.cmd</tt> 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.
```js
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
```js
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.
```js
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:
```js
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](#the-scripts-menu) 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:
```javascript
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`):
```javascript
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).
[[r 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.
```javascript
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:
```javascript
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.
```javascript
/**
* 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`.
```javascript
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](#services)).
## The Scripts Menu
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'.
```javascript
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:
<iframe width="854" height="480" src="https://www.youtube.com/embed/Lr-xFncadms" frameborder="0" allowfullscreen></iframe>
<!-- End of markdown source -->
<div id="footer"></div>
]]>