Basics

pyrcl is using the TRACE32 “Remote API” protocol. So in order to use the pyrcl module the TRACE32 software must be started with an open Remote API port.

Connecting to already running software

Preparing the TRACE32 software

The TRACE32 software has to be configured for use with a remote control, such as the API. If you are using Windows and T32Start application to start the TRAC32 software, you need to open the configuration at “advanced settings” where you can select “Use Port: yes” in the “API Port” folder. The automatically created config file will have the necessary lines automatically.

<mandatory blank line>

RCL=NETASSIST
PORT=20000
PACKLEN=1024

RCL=NETTCP
PORT=20000

<mandatory blank line>

To allow and configure remote control when not using T32Start application, add one of the above sections to the file “config.t32”. The section starting with NETASSIST enables the api to use UDP ports, the other section stating NETTCP enables the api to use a TCP port.

PACKLEN specifies the maximum package length in bytes for the UDP socket communication. It must not be bigger than 2048 and must fit to the value used to connect the client. The port number specifies the port which is used to communicate with the API. The default is 20000. If this port is already in use, try one higher than 20000.

Further information can be found in “api_remote_c.pdf” in your TRACE32 installation.

Importing

Make sure you have installed pyrcl.

import lauterbach.trace32.rcl as t32

Connecting

Connecting is done using t32.connect().

Connecting with default parameters

If you use default parameters, you can use:

import lauterbach.trace32.rcl as t32
dbg = t32.connect()

This will establish a connection to the remote api with default parameters. These translate to a TCP protocol with port 20000 at localhost and a timeout of 1 second.

Connecting with parameters

Otherwise you can specify the parameters when calling t32.connect().

import lauterbach.trace32.rcl as t32
dbg = t32.connect(node='localhost', port=20000, protocol="TCP", timeout=10.0)

or:

import lauterbach.trace32.rcl as t32
dbg = t32.connect(node='localhost', port=20000, protocol="UDP", packlen=1024, timeout=10.0)

Connecting to multiple debuggers

It is also possible to connect to multiple debuggers. Assuming you have two debuggers, one running with port 20000 (default) and one debugger two running with port 20001:

import lauterbach.trace32.rcl as t32
dbg1 = t32.connect()
dbg2 = t32.connect(port=20001)

Using arguments and autoconnect()

Since many usecases require to leave the port parameter variable upon skript execution, the rcl module offers a commandline friendly method t32.autoconnect(). This allows to omit the api port and node in the code and pass those parameters as arguments with the call of your script.

import lauterbach.trace32.rcl as t32
dbg = t32.autoconnect()
dbg.print("hello world")

python hello_world.py --node=server01 --port=20001