{"id":5293,"library":"lauterbach-trace32-rcl","title":"Lauterbach TRACE32 Remote Control Library","description":"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.","status":"active","version":"1.1.5","language":"en","source_language":"en","source_url":"https://github.com/lauterbach/python-trace32-rcl","tags":["embedded","debugging","hardware","trace32","automation"],"install":[{"cmd":"pip install lauterbach-trace32-rcl","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"T32Api","correct":"from lauterbach_trace32_rcl import T32Api"},{"note":"Commonly imported for robust error handling.","symbol":"T32Error","correct":"from lauterbach_trace32_rcl import T32Error"},{"note":"Used for type hinting or explicit handling of command results introduced in 1.1.0.","symbol":"T32CmdResult","correct":"from lauterbach_trace32_rcl import T32CmdResult"}],"quickstart":{"code":"import os\nfrom lauterbach_trace32_rcl import T32Api, T32Error\n\n# Ensure a TRACE32 instance with RCP server is running on localhost:20000.\n# For example, in TRACE32: MENU.OPTION RCPSERVER\n# or launch TRACE32 with the -RCL option: t32mppc.exe -RCL\nhost = os.environ.get(\"T32_HOST\", \"localhost\")\nport = int(os.environ.get(\"T32_PORT\", \"20000\"))\n\nt32 = None\ntry:\n    print(f\"Connecting to TRACE32 RCP server at {host}:{port}...\")\n    t32 = T32Api(host=host, port=port)\n    t32.connect()\n    print(\"Connected successfully.\")\n\n    # Execute a simple TRACE32 command\n    # The result is a T32CmdResult object since v1.1.0\n    result = t32.cmd(\"SYStem.CPU PowerPC\")\n    if result.ok:\n        print(f\"Command 'SYStem.CPU PowerPC' successful: {result.result_string}\")\n    else:\n        print(f\"Command failed: {result.result_string}\")\n\n    # Read a system variable (example: Program Counter)\n    # Note: Requires the debugger to be in a state where PC is valid\n    # The result is a T32VarResult object since v1.1.0\n    try:\n        pc_value = t32.variable_read(\"PC\")\n        if pc_value.ok:\n            print(f\"PC value: {pc_value.result_value:#010x}\")\n        else:\n            print(f\"Failed to read PC: {pc_value.result_string}\")\n    except T32Error as e:\n        print(f\"Error reading PC: {e}\")\n\nexcept T32Error as e:\n    print(f\"Error connecting or communicating with TRACE32: {e}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\nfinally:\n    if t32 and t32.is_connected():\n        t32.disconnect()\n        print(\"Disconnected from TRACE32.\")\n","lang":"python","description":"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."},"warnings":[{"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]`).","message":"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.","severity":"breaking","affected_versions":">=1.1.0"},{"fix":"Ensure `T32Api()` is called with appropriate `host` and `port` arguments, or confirm that the default values `('localhost', 20000)` are suitable for your setup.","message":"Breaking change in v1.0.0: The `T32Api` constructor signature was updated to explicitly accept `host` and `port` arguments, defaulting to `localhost` and `20000`.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}