Creating event-based trace step templates(创建事件驱动的 trace step 模板)

创建新 trace step 模板的流程已在章节 General approach(一般方法) 中说明。虽然信号和参数的创建方式对所有模板都相同,但具体分析逻辑的实现方式则明显不同。

对于事件驱动的 trace step 模板,用户可以创建自己的 Python 函数(即所谓的 Next 函数),并将其绑定到信号。将 Python 函数绑定到信号的目的在于, 在执行 Trace 分析时,ecu.test 会调用这些 Python 函数,并传入其所绑定信号的实际值。 请注意,Next 函数只会在一个或多个已绑定信号存在采样值的时间戳处被调用。

除这些 Python 函数外,还提供 Init 和 Finalize 函数。开发者可以在每次分析运行的开始和结束时调用它们,并填入相应的 Python 代码。

../../../../../_images/TraceStepTemplates_PythonEventBasedExample.png

Init 和 Finalize 函数的接口如下:

def Init(dataContainer, parameters, report):
    ...
def Finalize(dataContainer, parameters, report):
    ...

这两个函数被 ecu.test 调用时,会接收以下参数:

dataContainer:

用于访问 ecu.test 变量。 有关所传对象接口的说明,请参见 Trace Analysis API 文档。

parameters:

Python 字典,包含 trace step 中为模板里每个已定义参数指定的参数值。

report:

用于访问测试报告。 该对象接口的说明可参见 Trace Analysis API 文档。

绑定到信号的函数(Next 函数)接口如下:

def Next(event, hold, dataContainer, parameters, report):
    ...

这些函数会由 ecu.test 按时间先后顺序调用;凡是函数所绑定的某个信号在某个时间戳上存在测量值, 就会调用一次。如果多个信号在同一时间戳上都有测量值,函数仍只调用一次。该时间戳上所有具有测量值的信号, 都会通过参数 event 传递给函数。

上述函数被 ecu.test 调用时,会接收以下参数:

event:

用于访问当前 Trace 事件。可以在此查询时间戳(event.GetTime()) 以及当前信号值(event.GetValue("SignalName"))。有关所传对象接口的说明,请参见 Trace Analysis API 文档。

hold:

ecu.test 会传入一个对象,作为一种保持寄存器,保存该函数所绑定全部信号的最近已知值。 与 event 对象一样,也可以通过 hold.GetValue("SignalName") 查询信号值。 有关所传对象接口的说明,请参见 ecu.test API 文档。

dataContainer:

用于访问 ecu.test 变量和参数。 有关所传对象接口的说明,请参见 ecu.test API 文档。

parameters:

Python 字典,包含 trace step 中为模板里每个已定义参数指定的参数值。

report:

用于访问测试报告。 该对象接口的说明可参见 Trace Analysis API 文档。

信息

将 dataContainer 对象用作变量存储

按照 Python 的惯例,函数中使用的所有变量都是局部变量,这意味着每次函数调用时它们都会再次“为空”。 为了在多次调用之间保留中间结果,ecu.test 提供了 dataContainer 对象。 在一次分析运行期间,ecu.test 会将同一个 dataContainer 对象传递给一个 trace step 的所有函数。 因此可以用它来建立持久变量,例如在 Init 函数中通过 dataContainer.intermediateResult = 0 进行初始化。 之后即可在 Next 函数和 Finalize 函数中对该变量进行读写。

Example MinimumMaximum(示例 MinimumMaximum)

随附提供的 trace step 模板 “MinimumMaximum” 演示了基于 Python 的 trace step 模板的基本工作方式:

../../../../../_images/TraceStepTemplates_MinMaxExample.png

打开 Next 方法进行编辑的 MinimumMaximum trace step 模板

通过按钮 (1) 创建新信号。应在 (2) 处为其指定一个有明确含义的名称(本例中为 “Signal”)。该信号将 Recording 中的名称与 trace step 模板中使用的名称解耦,因此同一模板无需调整即可用于评估多个信号。 通过 (3) 创建新函数,并在 (4) 处为其指定新名称。按钮 (5) 用于选择在 Recording 中出现时会触发该函数调用的信号。

在本示例中,每次信号出现时都会调用 Next 函数。当前信号值会赋给变量 value(value = event.GetValue("Signal"))。

两个变量 dataContainer.min 和 dataContainer.max 在 Init 函数中初始化:

def Init(dataContainer, parameters, report):
    dataContainer.min = ''   # min(x, '') yields x
    dataContainer.max = None # max(x, None) yields x

最后,由 Finalize 函数输出结果:

def Finalize(dataContainer, parameters, report):
    report.SetResultText("Min: %s\nMax: %s" \
           % (dataContainer.min, dataContainer.max))

流程如下:

假设该信号依次具有 2、1、-5、6、0 这些值。第一次出现时会调用 Next 函数。变量 value 的值为 2。函数 min 对 datacontainer.min("")和 2 求值后得到 2,因此 datacontainer.min 中为 2。函数 max 对 datacontainer.max(None)和 2 求值后同样得到 2。 因此第一次函数调用后,datacontainer.min 和 datacontainer.max 中都为 2。第二次函数调用时,会对 2 和 1 分别执行 min 与 max,因此 datacontainer.min 中变为 1,而 datacontainer.max 中仍为 2。后续值也按相同方式处理, 因此最终 datacontainer.min 中为 -5,datacontainer.max 中为 6,并在 Finalize 函数中写入测试报告。

Adapting default templates using the example CalculateMinMax(以 CalculateMinMax 为例调整默认模板)

默认模板不能直接修改。不过,可以编辑默认模板的副本,并像自定义模板一样使用它。

在 Trace step templates 选项卡中,可以在 StandardTraceStepTemplates/Calculate 下的 Default templates 文件树中找到模板 “CalculateMinMax”。由于默认模板不能修改,必须先将其复制到 “My templates”。为此,请右键单击模板 CalculateMinMax,打开上下文菜单并选择 Copy。 然后在 “My templates” 的文件树中任意位置右键单击,例如右键单击文件夹 TraceStepTemplates,并在上下文菜单中选择 Paste。随后会弹出一个对话框,询问是否要更新使用模板 CalculateMinMax 的 Package 引用。 单击 No 关闭该对话框。现在,模板副本会显示在 “My templates” 的文件树中,双击即可编辑。

信息

如果自定义模板与某个默认模板使用相同的 ID,那么引用该 ID 时将执行自定义模板。 例如,如果 CalculateMinMax 的副本保存在文件夹 Calculate 中, 则自定义模板会覆盖默认模板的显示。