Overview

JavaScript is the default scripting language supported by DSS. However, DSS is implemented as a set of Java APIs, thus any language that supports importing and using Java classes can be used with DSS. Jython is an implementation of Python written in Java, and hence falls into this category.

Prerequisites

Software

  • Code Composer Studio (CCS) (preferably version 8 or later)
  • An installation of Jython (tested with Jython 2.7.0)

  • Compatible Java Runtime Environment (JRE), depending on the CCS version used (see the table)

    OS Requires 32-bit JDK Requires 64-bit JDK
    Windows Up to CCS v8.x CCS v9 and above
    MacOS None All
    Linux Up to CCS v6.1.3 CCS v6.2.0 and above

    The CCS installation contains a compatible JRE (can be found in <CCS_INSTALL_DIR>/eclipse/jre). To use it, make sure to point Jython to its location (can be done by setting the JAVA_HOME environment variable).

Setting Up the Environment

Before running a Jython DSS script, the following JAR files should be added to the CLASSPATH environment variable:

  • <CCS_BASE_DIR>/DebugServer/packages/ti/dss/java/dss.jar
  • <CCS_BASE_DIR>/DebugServer/packages/ti/dss/java/com.ti.ccstudio.scripting.environment_3.1.0.jar
  • <CCS_BASE_DIR>/DebugServer/packages/ti/dss/java/com.ti.debug.engine_1.0.0.jar

Here <CCS_BASE_DIR> refers to the ccs_base directory in the CCS installation. For example, in CCS 8 it would be <CCS_INSTALL_DIR>/ccsv8/ccs_base.

Tip:

This can be done in a batch/shell script to setup the environment before running Jython. You can even have the same batch/shell script run the Jython script afterwards to automate everything with the execution of one script.

Creating and Running a Jython script

Importing the DSS Java Classes

The following DSS Java classes should be imported by the Jython script:

from com.ti.debug.engine.scripting import *
from com.ti.ccstudio.scripting.environment import *

Now your Jython script can call the DSS APIs.

Running your Jython script

You can run your DSS Jython script as you would any other Jython script. For example:

jython my_script.py

Example Script

Below is an example DSS Jython script. It is a port of the msp430f5529_breakpoints.js example that comes with CCS (you can find the example in <CCS_BASE_DIR>/scripting/examples/DebugServerExamples/).

from java.lang import *
from java.util import *
from com.ti.debug.engine.scripting import *
from com.ti.ccstudio.scripting.environment import *

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

# Create a log file in the current directory to log script execution
script.traceBegin("BreakpointsTestLog_python.xml", "DefaultStylesheet.xsl")

# Set our TimeOut
script.setScriptTimeout(15000)

# Log everything
script.traceSetConsoleLevel(TraceLevel.ALL)
script.traceSetFileLevel(TraceLevel.ALL)

# Get the Debug Server and start a Debug Session
debugServer = script.getServer("DebugServer.1")
debugServer.setConfig("../msp430f5529/msp430f5529.ccxml");
debugSession = debugServer.openSession(".*")

debugSession.target.connect()

# Load a program
# (ScriptingEnvironment has a concept of a working folder and for all of the APIs which take
# path names as arguments you can either pass a relative path or an absolute path)
debugSession.memory.loadProgram("../msp430f5529/programs/modem.out")

# Set a breakpoint
address = debugSession.symbol.getAddress("ReadNextData")
bp = debugSession.breakpoint.add(address)

# Using an expression - get the current value of the PC
nPC = debugSession.expression.evaluate("PC")
scriptEnv.traceWrite("Current halted at {}. This should be at the start of main().".format(hex(nPC)))

# Run the target. Should halt at our breakpoint.
debugSession.target.run()

nPC = debugSession.expression.evaluate("PC")

# Verify we halted at the correct address.
if (nPC == address):
    script.traceWrite("SUCCESS: Halted at correct location")
else:
    script.traceWrite("FAIL: Expected halt at " + hex(address) + ", actually halted at " + hex(nPC))
    script.traceSetConsoleLevel(TraceLevel.INFO)
    script.traceWrite("TEST FAILED!")
    script.traceEnd()
    System.exit(1);

# All done
debugSession.terminate()
debugServer.stop()