ecutest.toolaccess

class ecutest.toolaccess.ToolAccess(init_timeout: float = 10.0, request_timeout: float = 10.0)

Interface for interacting with ecu.test jobs and variables in user-defined Python code.

A ToolAccess instance manages connection lifecycle, registration of jobs and variables, and execution state transitions (uninitialized <-> initialized <-> running).

Typical usage:

ta = ToolAccess()                       # unitialized state
with ta.init():                         # enter initialized state
    job = ta.job("PORT/SomeJob")        # register job
    var = ta.model_var("Model/Value")   # register variable
    with ta.run():                      # enter running state
        result = job(1, 2)              # call job
        current = var.read()            # read variable
        var.write(42)                   # write variable
    # by leaving the run context, ta falls back into the initialized state
# by leaving the init context, ta falls back into the unitialized state

The factory methods (job(), model_var(), meas_var(), calib_var(), bus_signal()) can only be invoked in the initialized state. read(), write(), call() and simu_wait() operations require the running state.

Parameters:
init_timeout: float = 10.0

Maximum time (in seconds) to wait for establishing a connection to ecu.test.

request_timeout: float = 10.0

Per-request timeout (in seconds) for API calls (read, write, job calls, …). You might want to increase this value e.g. when using long-running jobs.

simu_wait(timeout: float | int) → None

Waits the specified amount of time based on the active time basis in ecu.test (model time or system time).

Parameters:
timeout: float | int

Time to wait in seconds.

Raises:

  • RemoteError – If an error occurs in ecu.test during this function call.

  • StateError – If ToolAccess is not in the running state.

  • TimeoutError – If ecu.test does not respond within the configured request timeout.

bus_signal(name: str) → BusSignal

Create and register an ecu.test bus signal. Repeated calls with the same name parameter return the already registered instance and do not trigger an additional registration on the ecu.test side.

Parameters:
name: str

Fully qualified signal name (path).

Returns:

A registered BusSignal instance.

Raises:

  • RemoteError – If an error occurs in ecu.test during this function call.

  • StateError – If ToolAccess is not in the initialized state.

  • TimeoutError – If ecu.test does not respond within the configured request timeout.

model_var(name: str) → ModelVar

Create and register an ecu.test model variable. Repeated calls with the same name parameter return the already registered instance and do not trigger an additional registration on the ecu.test side.

Parameters:
name: str

Fully qualified model variable name (path).

Returns:

A registered ModelVar instance.

Raises:

  • RemoteError – If an error occurs in ecu.test during this function call.

  • StateError – If ToolAccess is not in the initialized state.

  • TimeoutError – If ecu.test does not respond within the configured request timeout.

meas_var(name: str) → MeasVar

Create and register an ecu.test measurement variable. Repeated calls with the same name parameter return the already registered instance and do not trigger an additional registration on the ecu.test side.

Parameters:
name: str

Fully qualified measurement variable name (path).

Returns:

A registered MeasVar instance.

Raises:

  • RemoteError – If an error occurs in ecu.test during this function call.

  • StateError – If ToolAccess is not in the initialized state.

  • TimeoutError – If ecu.test does not respond within the configured request timeout.

calib_var(name: str) → CalibVar

Create and register an ecu.test calibration variable. Repeated calls with the same name parameter return the already registered instance and do not trigger an additional registration on the ecu.test side.

Parameters:
name: str

Fully qualified calibration variable name (path).

Returns:

A registered CalibVar instance.

Raises:

  • RemoteError – If an error occurs in ecu.test during this function call.

  • StateError – If ToolAccess is not in the initialized state.

  • TimeoutError – If ecu.test does not respond within the configured request timeout.

diag_var(name: str) → DiagVar

Create and register an ecu.test diagnostic service variable. Repeated calls with the same name parameter return the already registered instance and do not trigger an additional registration on the ecu.test side.

Parameters:
name: str

Fully qualified diagnostic service name. The name must include the control unit identifier as defined in the test configuration and the diagnostic service name. Example: Engine/Read_data_by_identifier.

Returns:

A registered DiagVar instance.

Raises:

  • RemoteError – If an error occurs in ecu.test during this function call.

  • StateError – If ToolAccess is not in the initialized state.

  • TimeoutError – If ecu.test does not respond within the configured request timeout.

package(package_path: str) → Package

Create and register an ecu.test package. Repeated calls with the same name parameter return the already registered instance and do not trigger an additional registration on the ecu.test side.

There are some restrictions on the test steps used in the package. Many test steps do not make sense when the package is called from ecu.test code, and some could even cause problems. Therefore:

  • Test steps that open any kind of dialog during their execution are not allowed because ecu.test code is intended to run without user interaction.

  • Test steps related to parallel packages or Inbox/Outbox variables are not allowed because parallelism should be handled in the python script.

  • Test steps “Report”, “Log File Entry”, and “Exit”, as well as “Precondition” and “Postcondition” are not allowed because they only make sense when the entire test case is handled inside ecu.test.

  • “Start/Stop/Add Trace”, “Set Trace Comment”, as well as “Request Analysis” and “Incorporate trace step result” are not allowed because the trace analysis part of the package isn’t executed.

  • “Start/Stop Stimulus”, user-defined utilities, various tool specific test steps, and EES / FIU test steps are currently not allowed.

Packages containing such test steps cannot be used in this way at all.

Parameters:
package_path: str

Path to the package.

Returns:

A registered Package instance.

Raises:

  • RemoteError – If an error occurs in ecu.test during this function call.

  • StateError – If ToolAccess is not in the initialized state.

  • TimeoutError – If ecu.test does not respond within the configured request timeout.

init() → _ContextManager

Initialize the connection to ecu.test.

The initialized state is required before registering jobs or variables. Can be used as a context manager which will automatically invoke deinit() when leaving the context:

with ToolAccess().init() as ta:
    job = ta.job("PORT/Job")
    ...

Alternatively call it explicitly and later deinit():

ta = ToolAccess()
ta.init()
job = ta.job("PORT/Job")
...
ta.deinit()
Raises:

  • AuthenticationError – If ecu.test can not verify this client.

  • TimeoutError – If ecu.test does not respond within the configured init timeout.

deinit() → None

Close the connection to ecu.test and reset all registered variables and jobs. After calling this methode ToolAccess falls back into the initialized state.

Info

This method should only be called when init() was called explicitly before.

Raises:

StateError – If ToolAccess is not in the initialized state.

run() → _ContextManager

Enter the running state required for read / write / job calls / simu_wait.

Usable as a context manager which automatically invokes stop() after leaving the context:

with ta.run():
    value = var.read()
    ...

Or explicitly:

ta.run()
my_var.read()
...
ta.stop()
Raises:

  • RemoteError – If an error occurs in ecu.test during this function call.

  • StateError – If ToolAccess is not in the initialized state.

  • TimeoutError – If ecu.test does not respond within the configured request timeout.

stop() → None

Exit the running state and fall back into the initialized state. Depending on the used tools, this can restore defaults for variables which were altered during the running state.

Info

This method should only be called when run() was called explicitly before.

Raises:

StateError – If ToolAccess is not in the running state.

recording(dest_file: str, vars: list[BusSignal | ModelVar | MeasVar | CalibVar]) → Recording

Create a recording instance for the specified variables.

Parameters:
dest_file: str

Destination file path for the recording. Relative paths are interpreted as relative to

the current working directory of the script process.

A type-appropriate extension is automatically added, and if the file already exists,

extra characters are added to make it unique.

vars: list[BusSignal | ModelVar | MeasVar | CalibVar]

List of variables to record

Note

All variables must be realized via a single port in ecu.test. Otherwise, the port used by the majority of variables will be selected, and variables not realized via that port will not be recorded.

Returns:

A Recording instance

job(name: str) → Job

Create and register an ecu.test job. Repeated calls with the same name parameter return the already registered instance and do not trigger an additional registration on the ecu.test side.

Parameters:
name: str

Fully qualified job name.

Returns:

A registered Job instance.

Raises:

  • RemoteError – If an error occurs in ecu.test during this function call.

  • StateError – If ToolAccess is not in the initialized state.

  • TimeoutError – If ecu.test does not respond within the configured request timeout.

class ecutest.toolaccess.BusSignal

Represents a bus signal in ecu.test.

Warning

Do not instantiate this class manually! Always use ToolAccess.bus_signal() to create instances of this class.

read() → str | int | float | list | tuple | Vector | Matrix | Curve | Map | None

Read the current value of this variable from ecu.test.

Returns:

The value of the variable.

Raises:
write(value: str | int | float | list | tuple | Vector | Matrix | Curve | Map | None)

Write a new value to this variable in ecu.test.

Parameters:
value: str | int | float | list | tuple | Vector | Matrix | Curve | Map | None

The value to assign.

Raises:
class ecutest.toolaccess.ModelVar

Represents a model variable in ecu.test.

Warning

Do not instantiate this class manually! Always use ToolAccess.model_var() to create instances of this class.

read() → str | int | float | list | tuple | Vector | Matrix | Curve | Map | None

Read the current value of this variable from ecu.test.

Returns:

The value of the variable.

Raises:
write(value: str | int | float | list | tuple | Vector | Matrix | Curve | Map | None)

Write a new value to this variable in ecu.test.

Parameters:
value: str | int | float | list | tuple | Vector | Matrix | Curve | Map | None

The value to assign.

Raises:
class ecutest.toolaccess.MeasVar

Represents a measurement variable in ecu.test.

Warning

Do not instantiate this class manually! Always use ToolAccess.meas_var() to create instances of this class.

read() → str | int | float | list | tuple | Vector | Matrix | Curve | Map | None

Read the current value of this variable from ecu.test.

Returns:

The value of the variable.

Raises:
write(value: str | int | float | list | tuple | Vector | Matrix | Curve | Map | None)

Write a new value to this variable in ecu.test.

Parameters:
value: str | int | float | list | tuple | Vector | Matrix | Curve | Map | None

The value to assign.

Raises:
class ecutest.toolaccess.CalibVar

Represents a calibration variable in ecu.test.

Warning

Do not instantiate this class manually! Always use ToolAccess.calib_var() to create instances of this class.

read() → str | int | float | list | tuple | Vector | Matrix | Curve | Map | None

Read the current value of this variable from ecu.test.

Returns:

The value of the variable.

Raises:
write(value: str | int | float | list | tuple | Vector | Matrix | Curve | Map | None)

Write a new value to this variable in ecu.test.

Parameters:
value: str | int | float | list | tuple | Vector | Matrix | Curve | Map | None

The value to assign.

Raises:
class ecutest.toolaccess.DiagVar

Represents a callable ecu.test diagnostic service.

Calling this variable will execute the corresponding diagnostic service in ecu.test. The first argument or “param” keyword argument may be used to specify diagnostic parameters and values as a dictionary. The result of the service call will be returned as a dictionary containing the decodedResponseData.

Warning

Do not instantiate this class manually! Always use ToolAccess.diag_var() to create instances of this class.

__call__(*args, **kwargs) → Any

Invoke the diagnostic service with the specified arguments.

class ecutest.toolaccess.Package

Interface for packages.

You can preprocess and postprocess a package and run it.

Warning

Do not instantiate this class manually! Always use ToolAccess.package() to create instances of this class.

run(params: dict[str, Any] | None = None) → PackageResult

Run the package.

Parameters:
params: dict[str, Any] | None = None

Optional dictionary of parameter values for the package.

class ecutest.toolaccess.Recording

Interface for recording signals.

You can stop and start a recording multiple times.

If you stop and re-run the ToolAccess, recordings for which finish() has not been called, are lost.

finish() → list[dict[str, list[str] | str]]

Finalizes the recording and makes the recorded file(s) available. This requires ToolAccess to be in the initialized and stopped state.

Returns:

Information about the recordings: [{‘files: […], ‘type’: …}, …] Each list element corresponds to one start/stop pair. One recording typically consists of only one file, but in rare cases it can be split across several files.

start() → None

Starts the recording. This requires ToolAccess to be in the running state.

stop() → None

Stops the recording. This requires ToolAccess to be in the running state.

All recordings are also automatically stopped when the ToolAccess itself is stopped.

class ecutest.toolaccess.Job

Represents a callable ecu.test job.

Warning

Do not instantiate this class manually! Always use ToolAccess.job() to create instances of this class.

__call__(*args, **kwargs) → Any

Invoke the ecu.test job with the specified arguments.

class ecutest.toolaccess.PackageResult

Represents the result of an execution of a package in ecu.test.

result_code : ExecutionResult
return_values : None | dict[str, Any]
class ecutest.toolaccess.ExecutionResult

Bases: IntEnum

Represents the result of an execution of a package in ecu.test.

ERROR = 8
FAILED = 4
INCONCLUSIVE = 2
NONE = 0
SUCCESS = 1
class ecutest.toolaccess.Vector(values: list[int | float | str])

Represents a vector: an 1-dimensional array of values.

property length : int

Returns the length of the vector.

property values : list[int | float | str]

the values of the vector.

class ecutest.toolaccess.Matrix(values: list[list[int | float | str]])

Represents a matrix: a 2-dimensional array of values.

Values are in column-first layout, i.e. values[x][y] corresponds to the value at column x and row y.

property shape : tuple[int, int]

Returns the shape of the matrix as a tuple (number of columns, number of rows).

property values : list[list[int | float | str]]

the values of the matrix

class ecutest.toolaccess.Curve(x_axis: list[int | float | str], values: list[int | float | str])

Represents a curve: a 1-dimenstional table of values with corresponding x-axis values.

property length : int

Returns the length of the curve (number of points).

property values : list[int | float | str]

the values of the curve

property x_axis : list[int | float | str]

the x axis of the curve (the headings/labels for the values)

class ecutest.toolaccess.Map(x_axis: list[int | float | str], y_axis: list[int | float | str], values: list[list[int | float | str]])

Represents a map: a 2-dimensional table of values with corresponding x and y axes.

Values are in column-first layout, i.e. values[x][y] corresponds to the value at x-axis index x and y-axis index y.

property shape : tuple[int, int]

Returns the shape of the map as a tuple (number of columns, number of rows).

property values : list[list[int | float | str]]

the values of the map

property x_axis : list[int | float | str]

the x axis of the map (the headings/labels for the columns)

property y_axis : list[int | float | str]

the y axis of the map (the headings/labels for the rows)

ecutest.toolaccess.export_pyi(target_dir: str, **kwargs)

Create a pyi file with job information from the running ecu.test instance. The target directory should be named “ecutest-stubs” and located next to your own python code so your IDE will use it for code completion.

Additional arguments will be passed on to the communication module. See the webapi.WebApiClient for possible arguments