Lauterbach TRACE32 Remote Control Library

1.1.5 · active · verified Mon Apr 13

The `lauterbach-trace32-rcl` library provides a Python interface to control Lauterbach TRACE32 debuggers via their Remote Control Protocol (RCP). It enables automation of debugging tasks, script execution, and data extraction from TRACE32. The current version is 1.1.5, with releases typically tied to significant feature additions or TRACE32 protocol updates, implying a moderate release cadence.

Warnings

breaking Breaking change in v1.1.0: The return types for `T32Api.cmd()` and `T32Api.variable_read()` changed from `(bool, str)` or `(bool, Any)` tuples to dedicated `T32CmdResult` and `T32VarResult` objects, respectively.
Fix: Update code to access results via attributes (e.g., `result.ok`, `result.result_string`, `result.result_value`) instead of tuple indexing (e.g., `result[0]`).
breaking Breaking change in v1.0.0: The `T32Api` constructor signature was updated to explicitly accept `host` and `port` arguments, defaulting to `localhost` and `20000`.
Fix: Ensure `T32Api()` is called with appropriate `host` and `port` arguments, or confirm that the default values `('localhost', 20000)` are suitable for your setup.
gotcha This library requires a running Lauterbach TRACE32 debugger with the Remote Control Protocol (RCP) server enabled and accessible. Connection attempts will fail with a `T32Error` if the server is not active or configured correctly.
Fix: Before running your Python script, ensure TRACE32 is running and the RCP server is enabled (e.g., via `MENU.OPTION RCPSERVER` command in TRACE32, or by starting TRACE32 with the `-RCL` command-line option). Verify firewall rules if connecting remotely.
gotcha Communication with TRACE32 can lead to `T32Error` exceptions due to connection issues, timeouts, or invalid responses. The error messages from the library might be general.
Fix: Implement comprehensive `try...except T32Error` blocks. For detailed diagnostics, consult the TRACE32 console output or log files for server-side errors, especially for commands that result in unexpected behavior.

Install

pip install lauterbach-trace32-rcl Install latest version

Imports

T32Api

from lauterbach_trace32_rcl import T32Api

T32Error
```
from lauterbach_trace32_rcl import T32Error
```
Commonly imported for robust error handling.
T32CmdResult
```
from lauterbach_trace32_rcl import T32CmdResult
```
Used for type hinting or explicit handling of command results introduced in 1.1.0.

Quickstart

This quickstart demonstrates how to establish a connection to a running TRACE32 RCP server, execute a simple command, and read a system variable. It includes error handling and ensures proper disconnection. The `T32_HOST` and `T32_PORT` environment variables can be used to configure the connection, falling back to `localhost:20000` by default.

import os
from lauterbach_trace32_rcl import T32Api, T32Error

# Ensure a TRACE32 instance with RCP server is running on localhost:20000.
# For example, in TRACE32: MENU.OPTION RCPSERVER
# or launch TRACE32 with the -RCL option: t32mppc.exe -RCL
host = os.environ.get("T32_HOST", "localhost")
port = int(os.environ.get("T32_PORT", "20000"))

t32 = None
try:
    print(f"Connecting to TRACE32 RCP server at {host}:{port}...")
    t32 = T32Api(host=host, port=port)
    t32.connect()
    print("Connected successfully.")

    # Execute a simple TRACE32 command
    # The result is a T32CmdResult object since v1.1.0
    result = t32.cmd("SYStem.CPU PowerPC")
    if result.ok:
        print(f"Command 'SYStem.CPU PowerPC' successful: {result.result_string}")
    else:
        print(f"Command failed: {result.result_string}")

    # Read a system variable (example: Program Counter)
    # Note: Requires the debugger to be in a state where PC is valid
    # The result is a T32VarResult object since v1.1.0
    try:
        pc_value = t32.variable_read("PC")
        if pc_value.ok:
            print(f"PC value: {pc_value.result_value:#010x}")
        else:
            print(f"Failed to read PC: {pc_value.result_string}")
    except T32Error as e:
        print(f"Error reading PC: {e}")

except T32Error as e:
    print(f"Error connecting or communicating with TRACE32: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")
finally:
    if t32 and t32.is_connected():
        t32.disconnect()
        print("Disconnected from TRACE32.")

view raw JSON →