API Reference¶

Introduction¶

After connecting to the DebugServer, you can send commands in the form of requests. For every request sent the DebugServer will reply with a response. The general format of requests/responses are shown below:

Note

All requests and responses are in JSON format.

Requests¶

Requests are sent to the DebugServer to execute a command. A Request will always have a “name” field.

The “args” field is a JSON object representing the key-val arguments for the command

Key	Type	Description	Values	Required
“name”	String	Name of command to call		Always
“args”	JSON	Arguments to pass to command		When a command takes an argument(s)

//  Request
{
    "name": "commandName",
    "args": {
        "arg1": "value",
        "arg2": true
    }
}

Responses¶

Responses are sent back by the DebugServer after completing a Request. A Response will always have a “status” field which will either be “OK” (successful command) or “FAIL” (failed command).

The “data” field is present when a successful command returns a value.

The “message” field is present when a command raises an error.

Key	Type	Description	Values	Present
“status”	String	Result of a command	“OK” or “FAIL”	Always
“data”	Command specific	Return value of a command	Depends on command	When a command returns a value
“message”	String	Error message of failed command		When a command returns an error

//  Success Response
{
    "status": "OK",
    "data": <command return value>
}


//  Failure Response
{
    "status": "FAIL",
    "message": "Error message description"
}

Server Commands¶

Server commands are sent over a socket connected to the Debug Server port (received or specified when launching the debug server)

Command List:

setTimeout
getTimeout
setConsoleLevel
setConfig
getConfig
createConfig
getListOfCPUs
getListOfDevices
getListOfConnections
getListOfConfigurations
openSession
getListOfSessions
terminateSession
attachCCS
killServer

setTimeout ¶

Sets the timeout (how long to wait for a DS command to complete)

Request
Key	Value	Description
“name”	“setTimeout”	-
“args”	“timeout”	Value to set timeout to

//  Request
{
    "name": "setTimeout",
    "args": {
        "timeout": 300
    }
}

getTimeout ¶

Gets the timeout (how long to wait for a DS command to complete)

Request
Key	Value	Description
“name”	“getTimeout”	-
“args”	-	-

//  Request
{
    "name": "getTimeout",
}

//  Response
{
    "status": "OK",
    "data": -1,
}

setConsoleLevel ¶

Sets the console output level

Request

Key

Value

Description

“name”

“setConsoleLevel”

-

“args”

“level”

Log level to set console output:

“ALL”

“CONFIG”

“FINE”

“FINER”

“FINEST”

“INFO”

“SEVERE”

“WARNING”

“OFF”

//  Request
{
    "name": "setConsoleLevel",
    "args": {
        "level": "ALL"
    }
}

setConfig ¶

Sets the ccxml file for the DebugServer to use

Request
Key	Value	Description
“name”	“setConfig”	-
“args”	“path”	Full path to .ccxml file to use

//  Request
{
    "name": "setConfig",
    "args": {
        "path": "/path/to/config.ccxml"
    }
}

getConfig ¶

Returns the ccxml file the DebugServer is using

Request
Key	Value	Description
“name”	“getConfig”	-
“args”	-	-

//  Request
{
    "name": "getConfig",
}

Response
Key	Value	Description
“status”	String	“OK” or “FAIL”
“data”	String	Path to ccxml file

// Response
{
    "status": "OK",
    "data": "/path/to/config.ccxml"
}

createConfig ¶

Creates a ccxml configuration file

Request
Key	Value	Description
“name”	“createConfig”	-
“args”	“name”	Name of of ccxml file to create
	“connection”	Connection name to use
	“device”	Devicetype to use (optional)
	“board”	Board to use (optional)
	“directory”	Directory to place ccxml (optional)

//  Request
{
    "name": "createConfig",
    "args": {
        "name": "config.ccxml",
        "connection": "Texas Instruments XDS110 USB Debug Probe",
        "device": "CC1350F128",
        "directory": "/home/user/ti/CCSTargetConfigurations"
    }
}

Response
Key	Value	Description
“status”	String	“OK” or “FAIL”
“data”	JSON object	JSON object containing name of ccxml file and directory

// Response
{
    "status": "OK",
    "data": {
        "name": "config.ccxml",
        "directory": "/home/user/ti/CCSTargetConfigurations"
    }
}

getListOfCPUs ¶

Returns a list of CPU names which can be used for starting a session.

Request
Key	Value	Description
“name”	“getListOfCPUs”	-
“args”	-	-

//  Request
{
    "name": "getListOfCPUs",
}

Response
Key	Value	Description
“status”	String	“OK” or “FAIL”
“data”	Array	List of CPU names

// Response
{
    "status": "OK",
    "data": ["Cortex_M3", "Cortex_M0"]
}

getListOfDevices ¶

Returns a list of device names which can be used for creating ccxml files.

Request
Key	Value	Description
“name”	“getListOfDevices”	-
“args”	-	-

//  Request
{
    "name": "getListOfDevices"
}

Response
Key	Value	Description
“status”	String	“OK” or “FAIL”
“data”	Array	List of Device names

// Response
{
    "status": "OK",
    "data": ["CC1310F128", "CC1350F128"]
}

getListOfConnections ¶

Returns a list of connection names which can be used for creating ccxml files.

Request
Key	Value	Description
“name”	“getListOfConnections”	-
“args”	-	-

//  Request
{
    "name": "getListOfConnections"
}

Response
Key	Value	Description
“status”	String	“OK” or “FAIL”
“data”	Array	List of Connection names

// Response
{
    "status": "OK",
    "data": ["Texas Instruments XDS110 USB Debug Probe", "TI MSP430 USB1"]
}

getListOfConfigurations ¶

Returns a list of configuration (ccxml) file names.

Request
Key	Value	Description
“name”	“getListOfConfigurations”	-
“args”	-	-

//  Request
{
    "name": "getListOfConfigurations",
}

Response
Key	Value	Description
“status”	String	“OK” or “FAIL”
“data”	Array	List of configuration files

// Response
{
    "status": "OK",
    "data": ["L2000FF.ccxml", "L4000XX.ccxml"]
}

openSession ¶

Opens a session for the given CPU

Request
Key	Value	Description
“name”	“openSession”	-
“args”	“name”	CPU to open session with

//  Request
{
    "name": "openSession",
    "args": {
        "name": "*/Cortex_M3*"
    }
}

Response
Key	Value	Description
“status”	String	“OK” or “FAIL”
“data”	Integer	Port number session opened on

// Response
{
    "status": "OK",
    "data": 4444
}

getListOfSessions ¶

Returns a list of open sessions running on the DebugServer

Request
Key	Value	Description
“name”	“getListOfSessions”	-
“args”	-	-

//  Request
{
    "name": "getListOfSessions"
}

Response
Key	Value	Description
“status”	String	“OK” or “FAIL”
“data”	Array of JSON objects	List of JSON objects containing open session names and their port number

// Response
{
    "status": "OK",
    "data": [{
        "name": "Texas Instruments XDS110 USB Debug Probe/Cortex_M3",
        "port": 4445
    }, {
        "name": "Texas Instruments XDS110 USB Debug Probe/IcePick_M0",
        "port": 4446
    }]
}

terminateSession ¶

Terminates the specified session.

Warning

The session’s socket should be closed by the client before terminating the session to avoid deadlock.

Request
Key	Value	Description
“name”	“terminateSession”	-
“args”	“name”	Name of session to terminate

//  Request
{
    "name": "terminateSession",
    "args": {
        "name": "Texas Instruments XDS110 USB Debug Probe/Cortex_M3"
    }
}

attachCCS ¶

Open and attach a CCS workbench to the Debug Session

Caution

You can only attach a CCS workbench once per Debug Server. If you exit out of the CCS IDE, you’ll have to restart the Debug Server in order to attach again.

Request
Key	Value	Description
“name”	“attachCCS”	-
“args”	-	-

//  Request
{
    "name": "attachCCS"
}

killServer ¶

Terminates all open sessions and shuts the Debug Server down.

Warning

All open session sockets should be closed before killing the server to avoid deadlock.

Request
Key	Value	Description
“name”	“killServer”	-
“args”	-	-

//  Request
{
    "name": "killServer"
}

Session Commands¶

Session commands are sent over a socket connected to the respective session port (received when opening a session)

Important

You must first open a session on the DebugServer and connect to it over a socket before sending any session commands.

Command List:

connect
disconnect
erase
reset
load
verify
evaluate
readData
writeData
readRegister
writeRegister
getOption
setOption
performOperation
run
halt
stop

connect ¶

Connect to the target

Request
Key	Value	Description
“name”	“connect”	-
“args”	-	-

//  Request
{
    "name": "connect"
}

disconnect ¶

Disconnect from the target

Request
Key	Value	Description
“name”	“disconnect”	-
“args”	-	-

//  Request
{
    "name": "disconnect"
}

erase ¶

Erases flash on target (must be connected to device)

Request
Key	Value	Description
“name”	“erase”	-
“args”	-	-

//  Request
{
    "name": "erase"
}

reset ¶

Resets device (must be connected to device)

Request
Key	Value	Description
“name”	“reset”	-
“args”	-	-

//  Request
{
    "name": "reset"
}

load ¶

Loads file into device’s flash (must be connected to device)

Request
Key	Value	Description
“name”	“load”	-
“args”	“file”	Path to file to load
	“binary”	Load image as binary (optional; default=false)
	“address”	Address location to load binary image (optional)

//  Request
{
    "name": "load",
    "args": {
        "file": "/path/to/image.hex"
    }
}

//  Request (binary)
{
    "name": "load",
    "args": {
        "file": "/path/to/image.bin",
        "binary": true,
        "address": 0x10000000
    }
}

verify ¶

Verifies a file in device’s memory (must be connected to device)

Request
Key	Value	Description
“name”	“verify”	-
“args”	“file”	Path to file to verify”
	“binary”	Verify image as binary (optional; default=false)
	“address”	Address location to verify binary image (optional)

//  Request
{
    "name": "verify",
    "args": {
        "file": "/path/to/image.hex"
    }
}

//  Request (binary)
{
    "name": "verify",
    "args": {
        "file": "/path/to/image.bin",
        "binary": true,
        "address": 0x10000000
    }
}

evaluate ¶

Evaluates an expression (must be connected to device)

Request
Key	Value	Description
“name”	“evaluate”	-
“args”	“expression”	Expression to evaluate
“args”	“file”	Path to symbols (.out) file to load first (optional)

//  Request (with symbols)
{
    "name": "evaluate",
    "args": {
        "expression": "&Sensor_msgStats",
        "file": "/path/to/symbols.out",
    }
}


//  Response
{
    "status": "OK",
    "data": 51234234
}

readData ¶

Read memory from device (must be connected to device)

Request
Key	Value	Description
“name”	“readData”	-
“args”	“page”	Page number to read address from
	“address”	Address to read memory from
	“numBytes”	Number of bytes to read starting at ‘address’

//  Request
{
    "name": "readData",
    "args": {
        "page": 0,
        "address": 0x20000000,
        "numBytes": 4
    }
}


//  Response
{
    "status": "OK",
    "data": [0xFF, 0xFF, 0xFF, 0xFF]
}

writeData ¶

Write to memory on device (must be connected to device)

Request
Key	Value	Description
“name”	“writeData”	-
“args”	“page”	Page number of address to write to
	“address”	Memory address to write to
	“data”	Byte or bytes to write to memory at ‘address’

//  Request
{
    "name": "writeData",
    "args": {
        "page": 0,
        "address": 0x20000000,
        "data": [0xFF, 0xFF]
    }
}


//  Response
{
    "status": "OK"
}

readRegister ¶

Read device register (must be connected to device)

Request
Key	Value	Description
“name”	“readRegister”	-
“args”	“name”	Name of register to read from

//  Request
{
    "name": "readRegister",
    "args": {
        "name": "R1"
    }
}


//  Response
{
    "status": "OK",
    "data": 0xFFFF
}

writeRegister ¶

Write to device’s register (must be connected to device)

Request
Key	Value	Description
“name”	“writeRegister”	-
“args”	“name”	Name of register to write to
“args”	“value”	Value to write to register

//  Request
{
    "name": "writeRegister",
    "args": {
        "name": "R1",
        "value": 0xBEEF
    }
}


//  Response
{
    "status": "OK"
}

getOption ¶

Get the value of a device option (must be connected to device)

Request
Key	Value	Description
“name”	“getOption”	-
“args”	“id”	option ID

//  Request
{
    "name": "getOption",
    "args": {
        "id": "DeviceInfoRevision"
    }
}


//  Response
{
    "status": "OK",
    "data": "2.1"
}

setOption ¶

Set the value of a device option (must be connected to device)

Request
Key	Value	Description
“name”	“setOption”	-
“args”	“id”	option ID
“args”	“value”	Value to set option to

//  Request
{
    "name": "setOption",
    "args": {
        "id": "ResetOnRestart",
        "value": True
    }
}


//  Response
{
    "status": "OK"
}

performOperation ¶

Perform flash operation (must be connected to device)

Request
Key	Value	Description
“name”	“performOperation”	-
“args”	“opcode”	operation code for flash operation

//  Request
{
    "name": "performOperation",
    "args": {
        "opcode": "Erase",
    }
}


//  Response
{
    "status": "OK"
}

run ¶

Issue run command to target device

Request
Key	Value	Description
“name”	“run”	-
“args”	“asynchronous”	run and return control immediately (default=False)

Warning

If “async” is set to False, this function will not return until one of the following occur:

target is halted due to hitting a breakpoint

target hits end of program

timeout

//  Request
{
    "name": "run",
    "args": {
        "async": True
    }
}

halt ¶

Issue halt command to target device

Request
Key	Value	Description
“name”	“halt”	-
“args”	“wait”	wait until device is actually halted before returning

//  Request
{
    "name": "halt",
    "args": {
        "wait": True
    }
}

stop ¶

Stop the session thread (does not terminate session)

Request
Key	Value	Description
“name”	“stop”	-
“args”	-	-

//  Request
{
    "name": "stop"
}