ecutest.toolaccess

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

用于在用户自定义 Python 代码中与 ecu.test 的 job 和变量交互的接口。

ToolAccess 实例负责管理连接生命周期、job 与变量的注册, 以及执行状态切换(uninitialized <-> initialized <-> running)。

典型用法:

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

工厂方法(job()、model_var()、meas_var()、calib_var()、 bus_signal())只能在 initialized 状态下调用。 执行 read()、write()、call() 和 simu_wait() 操作时需要处于 running 状态。

Parameters:
init_timeout: float = 10.0

建立到 ecu.test 连接时允许等待的最长时间(秒)。

request_timeout: float = 10.0

API 调用(read、write、 job 调用等)的单次请求超时时间,单位为秒。使用运行时间较长的 job 时,你可能需要适当增大该值。

simu_wait(timeout: float | int) → None

按 ecu.test 中当前生效的时间基准(模型时间或系统时间)等待指定时长。

Parameters:
timeout: float | int

等待时间,单位为秒。

Raises:
  • RemoteError – 如果在此函数调用期间 ecu.test 中发生错误。

  • StateError – 如果 ToolAccess 不处于 running 状态。

  • TimeoutError – 如果 ecu.test 在配置的请求超时时间内没有响应。

bus_signal(name: str) → BusSignal

创建并注册一个 ecu.test 总线信号。使用相同的名称参数重复调用时, 会返回已注册的实例,而不会在 ecu.test 侧再次触发注册。

Parameters:
name: str

完全限定的信号名称(路径)。

Returns:

一个已注册的 BusSignal 实例。

Raises:
  • RemoteError – 如果在此函数调用期间 ecu.test 中发生错误。

  • StateError – 如果 ToolAccess 不处于 initialized 状态。

  • TimeoutError – 如果 ecu.test 在配置的请求超时时间内没有响应。

model_var(name: str) → ModelVar

创建并注册一个 ecu.test 模型变量。使用相同 name 参数重复调用时,会返回已注册的实例,不会在 ecu.test 侧触发额外注册。

Parameters:
name: str

完全限定的模型变量名称(路径)。

Returns:

已注册的 ModelVar 实例。

Raises:
  • RemoteError – 如果在此函数调用期间 ecu.test 中发生错误。

  • StateError – 如果 ToolAccess 不处于 initialized 状态。

  • TimeoutError – 如果 ecu.test 在配置的请求超时时间内没有响应。

meas_var(name: str) → MeasVar

创建并注册一个 ecu.test 测量变量。使用相同 name 参数重复调用时,返回已注册的实例,不会在 ecu.test 侧触发额外注册。

Parameters:
name: str

完全限定的测量变量名称(路径)。

Returns:

一个已注册的 MeasVar 实例。

抛出:
  • RemoteError – 如果在此函数调用期间 ecu.test 中发生错误。

  • StateError – 如果 ToolAccess 不处于 initialized 状态。

  • TimeoutError – 如果 ecu.test 在配置的请求超时时间内没有响应。

calib_var(name: str) → CalibVar

创建并注册一个 ecu.test 标定变量。使用相同的名称参数重复调用时, 会返回已注册的实例,而不会在 ecu.test 侧再次触发注册。

Parameters:
name: str

完全限定的标定变量名称(路径)。

Returns:

一个已注册的 CalibVar 实例。

Raises:
  • RemoteError – 如果在此函数调用期间 ecu.test 中发生错误。

  • StateError – 如果 ToolAccess 不处于 initialized 状态。

  • TimeoutError – 如果 ecu.test 在配置的请求超时时间内没有响应。

diag_var(name: str) → DiagVar

创建并注册一个 ecu.test 诊断服务变量。使用相同的名称参数重复调用时, 会返回已注册的实例,而不会在 ecu.test 侧再次触发注册。

Parameters:
name: str

完全限定的诊断服务名称。该名称必须包含测试配置中定义的控制单元标识符 以及诊断服务名称。 示例:Engine/Read_data_by_identifier。

Returns:

一个已注册的 DiagVar 实例。

Raises:
  • RemoteError – 如果在此函数调用期间 ecu.test 中发生错误。

  • StateError – 如果 ToolAccess 不处于 initialized 状态。

  • TimeoutError – 如果 ecu.test 在配置的请求超时时间内没有响应。

package(package_path: str) → Package

创建并注册一个 ecu.test Package。使用相同的名称参数重复调用时,将返回已注册的实例,而不会在 ecu.test 侧触发额外注册。

对 Package 中使用的 test step 存在一些限制。由于从 ecu.test code 调用 Package 时,许多 test step 并不适用,某些 test step 甚至可能引发问题。因此:

  • 执行期间会打开任何类型对话框的 test step 不允许使用,因为 ecu.test code 设计为在无用户交互的情况下运行。

  • 与并行 Package 或 Inbox/Outbox 变量相关的 test step 不允许使用,因为并行处理应在 Python 脚本中完成。

  • test step “Report”、“Log File Entry”和“Exit”,以及 “Precondition”和“Postcondition”不允许使用,因为它们只有在 整个 test case 都在 ecu.test 内处理时才有意义。

  • “Start/Stop/Add Trace”、“Set Trace Comment”以及“Request Analysis”和“Incorporate trace step result”不允许使用,因为 Package 的 Trace 分析部分不会执行。

  • “Start/Stop Stimulus”、用户自定义 utility、各种工具专用 test step,以及 EES / FIU test step 当前均不允许使用。

包含这类 test step 的 Package 完全不能通过这种方式使用。

Parameters:
package_path: str

Package 的路径。

Returns:

一个已注册的 Package 实例。

Raises:
  • RemoteError – 如果在此函数调用期间 ecu.test 中发生错误。

  • StateError – 如果 ToolAccess 不处于 initialized 状态。

  • TimeoutError – 如果 ecu.test 在配置的请求超时时间内没有响应。

init() → _ContextManager

初始化与 ecu.test 的连接。

在注册 job 或变量之前,需要处于 initialized 状态。可以将其用作上下文管理器,离开上下文时会自动调用 deinit():

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

也可以显式调用它,之后调用 deinit():

ta = ToolAccess()
ta.init()
job = ta.job("PORT/Job")
...
ta.deinit()
Raises:
  • AuthenticationError – 如果 ecu.test 无法验证此客户端。

  • TimeoutError – 如果 ecu.test 在配置的初始化超时时间内没有响应。

deinit() → None

关闭与 ecu.test 的连接,并重置所有已注册的变量和 job。 调用此方法后,ToolAccess 回退到 initialized 状态。

Info

仅当此前已显式调用 init() 之后,才应调用此方法。

Raises:

StateError – 如果 ToolAccess 不处于 initialized 状态。

run() → _ContextManager

进入 read / write / job calls / simu_wait 所需的 running 状态。

可用作上下文管理器,在离开上下文后会自动调用 stop():

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

或者显式指定:

ta.run()
my_var.read()
...
ta.stop()
Raises:
  • RemoteError – 如果在此函数调用期间 ecu.test 中发生错误。

  • StateError – 如果 ToolAccess 不处于 initialized 状态。

  • TimeoutError – 如果 ecu.test 在配置的请求超时时间内没有响应。

stop() → None

退出 running 状态并回退到 initialized 状态。取决于所用的工具,这可能会将 running 状态期间修改过的变量恢复为默认值。

Info

仅当此前已显式调用 run() 之后,才应调用此方法。

Raises:

StateError – 如果 ToolAccess 不处于 running 状态。

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

为指定变量创建一个 Recording(测量记录)实例。

Parameters:
dest_file: str

Recording 的目标文件路径。相对路径会被解释为相对于

脚本进程的当前工作目录。

系统会自动添加与类型匹配的扩展名;如果文件已存在,

则会附加额外字符以确保文件名唯一。

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

要记录的变量列表

Note

所有变量都必须通过 ecu.test 中的单个 port 实现。否则,将选择大多数变量使用的 port,未通过该 port 实现的变量将不会被记录。

Returns:

一个 Recording 实例

job(name: str) → Job

创建并注册一个 ecu.test job。使用相同 name 参数重复调用会返回已注册的实例,不会在 ecu.test 侧触发额外的注册。

Parameters:
name: str

完全限定的 job 名称。

Returns:

一个已注册的 Job 实例。

Raises:
  • RemoteError – 如果在此函数调用期间 ecu.test 中发生错误。

  • StateError – 如果 ToolAccess 不处于 initialized 状态。

  • TimeoutError – 如果 ecu.test 在配置的请求超时时间内没有响应。

class ecutest.toolaccess.BusSignal

表示 ecu.test 中的总线信号。

Warning

切勿手动实例化此类!请始终使用 ToolAccess.bus_signal() 创建该类的实例。

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

从 ecu.test 读取该变量的当前值。

Returns:

变量的值。

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

在 ecu.test 中为该变量写入新值。

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

要赋的值。

Raises:
class ecutest.toolaccess.ModelVar

表示 ecu.test 中的模型变量。

Warning

不要手动实例化此类!请始终使用 ToolAccess.model_var() 来 创建此类的实例。

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

从 ecu.test 读取该变量的当前值。

Returns:

变量的值。

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

在 ecu.test 中为该变量写入新值。

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

要赋的值。

Raises:
class ecutest.toolaccess.MeasVar

表示 ecu.test 中的测量变量。

Warning

切勿手动实例化此类!请始终使用 ToolAccess.meas_var() 创建该类的实例。

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

从 ecu.test 读取该变量的当前值。

Returns:

变量的值。

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

在 ecu.test 中为该变量写入新值。

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

要赋的值。

Raises:
class ecutest.toolaccess.CalibVar

表示 ecu.test 中的标定变量。

Warning

不要手动实例化此类!请始终使用 ToolAccess.calib_var() 创建此类的实例。

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

从 ecu.test 读取该变量的当前值。

Returns:

变量的值。

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

在 ecu.test 中为该变量写入新值。

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

要赋的值。

Raises:
class ecutest.toolaccess.DiagVar

表示一个可调用的 ecu.test 诊断服务。

调用此变量将在 ecu.test 中执行相应的诊断服务。 第一个参数或“param”关键字参数可用于以字典形式指定诊断 参数和值。 服务调用的结果将以包含 decodedResponseData 的字典形式返回。

Warning

不要手动实例化此类!请始终使用 ToolAccess.diag_var() 创建此类的实例。

__call__(*args, **kwargs) → Any

使用指定的参数调用诊断服务。

class ecutest.toolaccess.Package

Package 的接口。

可以对 Package 进行预处理和后处理,并运行它。

Warning

不要手动实例化此类!请始终使用 ToolAccess.package() 创建此类的实例。

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

运行该 Package。

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

Package 参数值的可选字典。

class ecutest.toolaccess.Recording

用于记录信号的接口。

可以多次停止和启动 Recording。

如果停止并重新运行 ToolAccess,则未调用 finish() 的 Recording 会丢失。

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

结束 Recording 并使已记录的文件可用。 这要求 ToolAccess 处于 initialized 和 stopped 状态。

Returns:

关于 Recording 的信息: [{‘files: […], ‘type’: …}, …] 每个列表元素对应一个 start/stop 对。 一个 Recording 通常只包含一个文件,但在少数情况下 也可能分散在多个文件中。

start() → None

启动 Recording。这要求 ToolAccess 处于运行状态。

stop() → None

停止 Recording。这要求 ToolAccess 处于运行状态。

停止 ToolAccess 本身时,所有 Recording 也会自动停止。

class ecutest.toolaccess.Job

表示一个可调用的 ecu.test job。

Warning

不要手动实例化此类!请始终使用 ToolAccess.job() 创建此类的实例。

__call__(*args, **kwargs) → Any

使用指定参数调用 ecu.test 作业。

class ecutest.toolaccess.PackageResult

表示 Package 在 ecu.test 中一次执行的结果。

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

Bases: IntEnum

表示 Package 在 ecu.test 中一次执行的结果。

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

表示一个 vector:一维的值数组。

property length : int

返回向量的长度。

property values : list[int | float | str]

vector 的值。

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

表示矩阵:值的二维数组。

值采用列优先布局,即 values[x][y] 对应第 x 列、第 y 行的值。

property shape : tuple[int, int]

以元组(列数、行数)的形式返回矩阵的形状。

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

矩阵的值

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

表示一条曲线:带有对应 x 轴值的一维数值表。

property length : int

返回曲线的长度(点数)。

property values : list[int | float | str]

曲线的值

property x_axis : list[int | float | str]

curve 的 x 轴(各数值的表头/标签)

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

表示一个 map:带对应 x 轴和 y 轴的二维数值表。

数值按列优先布局,即 values[x][y] 对应于 x 轴索引 x 与 y 轴索引 y 处的值。

property shape : tuple[int, int]

以元组(列数、行数)形式返回该 map 的形状。

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

map 的值

property x_axis : list[int | float | str]

map 的 x 轴(各列的表头/标签)

property y_axis : list[int | float | str]

Map 的 y 轴(各行的标题/标签)

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

根据正在运行的 ecu.test 实例中的作业信息创建一个 pyi 文件。 目标目录应命名为“ecutest-stubs”,并位于您自己的 Python 代码旁边, 以便 IDE 将其用于代码补全。

其他参数将传递给通信模块。可能的参数请参见 webapi.WebApiClient