Event based tracestep templates¶

DataContainer¶

class traceAnalysisAPI.DataContainer¶

The DataContainer is a container to buffer values during the execution of Python based trace steps.

To assign a <value> to an arbitrary <key> just write:

dataContainer.<key> = <value>

Example:

dataContainer.index = 0

EmitSignal(time, traceStepSignalName, value)¶

Emits a signal event back into the current trace analysis session.

Parameters:

time : float¶: timeStamp of the emitted signal event
traceStepSignalName : string¶: the name of the tracesteps output signal that should be emitted (see TraceStep.DefineOutSignals())
value : float¶: the value of the emitted signal

GetTemplateSignalNames()¶

Returns the names of all user defined signal names in the trace step template.

Returns:: names of all user defined signal names in the trace step template
Return type:: list of strings

GetGenericSignalName(templateSignalName)¶

Returns the name of the assigned generic signal for a given signal name of the trace step template.

Parameters:

templateSignalName : string¶: name of the template signal

Returns:

name of the generic signal

Return type:

string

GetMappingItemName(templateSignalName)¶

Returns the name (of the reference (= source)) of the mapping item which corresponds to the assigned generic signal for a given signal name of the trace step template.

Parameters:

templateSignalName : string¶: name of the template signal

Returns:

name (of the reference (= source)) of the mapping item

Return type:

string

GetOriginalSignalName(templateSignalName)¶

Returns the original signal name of the assigned generic signal for a given signal name of the trace step template.

Parameters:

templateSignalName : string¶: name of the template signal

Returns:

name of the original signal

Return type:

string

GetRecordingInfo(templateSignalName)¶

Returns the RecordingInfo of the assigned generic signal for a given signal name of the trace step template. If the returned value is not None, one can call the methods GetPath(), GetRecordingName(), GetRecordingNumber() and GetRecordingType() on the returned RecordingInfo object to obtain further information.

Parameters:

templateSignalName : string¶: name of the template signal

Returns:

RecordingInfo if the source of the assigned generic signal is a recording else None

Return type:

RecordingInfo or None

GetGlobalConstantNames()¶

Returns a list of names containing all global constants.

Returns:: A list of names.
Return type:: list

GetGlobalConstant(name)¶

Returns the value of the given global constant.

Parameters:

name : string¶: The name of the constant to retrieve the value.

Returns:

The value of the constant.

Return type:

object

IsSignalInRecording(templateSignalName)¶

Returns whether the signal associated with the given template signal was found in the recording specified by GetRecordingInfo().

Parameters:

templateSignalName : string¶: name of the template signal

Returns:

True if the associated signal was found in the corresponding recording else False

Return type:

bool

GetUnit(templateSignalName: str)¶

Returns the unit of the signal with the given name.

Parameters:

templateSignalName : string¶: name of the template signal

Returns:

The unit of the given signal.

Return type:

str

GetTextTable(templateSignalName: str)¶

Returns the text table and the default value of the signal with the given name as tuple.

Parameters:

templateSignalName : string¶: name of the template signal

Returns:

The text table and the default text table as tuple.

Return type:

tuple

Report¶

class traceAnalysisAPI.Report¶

AddResultColumn(name: str) → None¶

Adds a new column with the given name to the result table. It is appended at the end of the table. Values can be inserted into this column by using the parameter “additionalInfo” of the methods Spot() and Range(). The entries in the list “additionalInfo” list are inserted into the additional result columns in sequence.

Parameters:

name: str¶: name of the new column

GetLastTable() → ReportTable¶: Returns the last table created.

GetResultId() → int | None¶

Gets the current result id.

The result id passed to an earlier call to SetResultId() is returned. If SetResultId() wasn’t called before, dataContainer.RESULT_ID_NONE is returned.

Returns:: the result id

GetTable(tableId: str | int) → ReportTable¶

Returns the table with the given id.

Parameters:

tableId: str | int¶: id of the table

GetTableByIndex(index: int) → ReportTable¶

Returns the table by the given position in the list of user-defined tables.

Parameters:

index: int¶: the position of the table

GetTableCount() → int¶

Returns the count of tables.

Returns:: The count of tables.

HasTable(tableId: str | int) → bool¶

Returns whether a particular table exists for the trace step.

Parameters:

tableId: str | int¶: id of the table

Returns:

True if a table with the given id exists, else False

Adds the given image to the test report. If the image is not embedded in the test report, the file will be stored in the report folder. If there is already an image with the same name, the image files will be enumerated.

Parameters:

imageSource: str | Path | ImageInterface | ndarray | bytes¶

The image source can be one of the following:

an absolute file path
an Image or Frame object
a NumPy array in OpenCV style: shape is (height, width, 3) of type numpy.uint8, the three colors have the order BGR!
bytes object with image data

name: str | None = None¶

The filename (with correct extension). Will be used as filename if an image file is created in the report folder. If name is None and the source is a path or an Image or Frame, the name of the imageSource is used.

title: str | None = None¶

the image title

embedded: bool = False¶

True, if the image file should be embedded in the test report, else the image file is stored in the test report folder.

limitPreviewSize: bool = True¶

If True (default), the preview image shown in the report will be limited to a maximum size.

autoDelete: bool = False¶

Only applicable if imageSource is a file path. True, if the image file should be automatically deleted, else False.

useTemp: bool = True¶

Only applicable if imageSource is a file path. True, if the image file should be copied into a temporary directory, False, if it should be used directly. Using a temporary copy might be necessary to avoid overriding the image before the final report gets assembled later on.

Log(level: int, time: float, message: str, *formatArgs, **formatKwargs) → None¶

Adds a log message to the trace analysis log file. Use SetLogComponent() to set the component part of the log entry.

Parameters:

level: int¶

log level

report.LOG_LEVEL_DEBUG
report.LOG_LEVEL_INFO
report.LOG_LEVEL_WARNING
report.LOG_LEVEL_ERROR

time: float¶

timestamp of the log message

message: str¶

log message or format string.

*formatArgs¶

additional non-keyword arguments used when message is a format string

**formatKwargs¶

additional keyword arguments used when message is a format string

Note:

The usage of a format string and its arguments is corresponding to str.format (external link).

Example:

report.Log(
    report.LOG_LEVEL_WARNING,
    1.3,
    "Signal exceeds threshold {1:f}! Value {0:.5f}",
    currentValue,
    myThreshold,
)
report.Log(
    report.LOG_LEVEL_ERROR,
    1.3,
    "Signal exceeds threshold {threshold:f}! Value {value:.5f}",
    threshold=myThreshold,
    value=currentValue,
)

LogDebug(time: float, message: str, *formatArgs, **formatKwargs) → None¶: Convenience method to add a debug log message. See Log() for further usage.

LogError(time: float, message: str, *formatArgs, **formatKwargs) → None¶: Convenience method to add an error log message. See Log() for further usage.

LogInfo(time: float, message: str, *formatArgs, **formatKwargs) → None¶: Convenience method to add an info log message. See Log() for further usage.

LogWarning(time: float, message: str, *formatArgs, **formatKwargs) → None¶: Convenience method to add a warning log message. See Log() for further usage.

Adds a range to the test report and returns a range object.

Parameters:

startTime: float | numpy.integer | numpy.floating¶: timestamp at which the range begins
endTime: float | numpy.integer | numpy.floating¶: timestamp at which the range ends
message: str = ''¶: a textual message describing the range
resultId: int | None = None¶: the verdict for the range
additionalInfo: list[str] | None = None¶: a list of additional information, that will be shown in the custom result columns (see AddResultColumn())

RemoveTable(tableId: str | int) → None¶

Removes a table from the test report.

Parameters:

tableId: str | int¶: id of the table

SetLogComponent(component: str) → None¶

Sets the component that will be used in logging entries created by calling log methods.

Parameters:

component: str¶: name of the component

SetResultError() → None¶: Convenience method for report.SetResultId(report.RESULT_ID_ERROR)

SetResultFailed() → None¶: Convenience method for report.SetResultId(report.RESULT_ID_FAILED)

SetResultId(resultId: int | None) → None¶

Sets the result id for the current trace step.

The result id can be one of:

report.RESULT_ID_NONE
report.RESULT_ID_SUCCESS
report.RESULT_ID_INCONCLUSIVE
report.RESULT_ID_FAILED
report.RESULT_ID_ERROR

The result id is set directly. It is not affected by earlier calls to SetResultId().

Example:

report.SetResultId(report.RESULT_ID_ERROR)
report.SetResultId(report.RESULT_ID_NONE)

report.GetResultId() # this will result in report.RESULT_ID_NONE

Parameters:

resultId: int | None¶: the result id to set

SetResultInconclusive() → None¶: Convenience method for report.SetResultId(report.RESULT_ID_INCONCLUSIVE)

SetResultSuccess() → None¶: Convenience method for report.SetResultId(report.RESULT_ID_SUCCESS)

SetResultText(text: str | None) → None¶

Sets a user-defined text for the result of the report.

Parameters:

text: str | None¶: the text

Adds a signal spot to the test report.

Parameters:

time: float | numpy.integer | numpy.floating¶: timestamp of the spot
message: str | None = ''¶: a textual message describing the spot
resultId: int | None = None¶: the verdict for the spot
additionalInfo: list[str] | None = None¶: a list of additional information, that will be shown in the custom result columns (see AddResultColumn())

Table(tableId: str | int | None = None, headerValues: Iterable[str | int] | None = None) → ReportTable¶

Creates a table in the test report.

Example:

table = report.Table("table1", ["time", "description"])
table.AddRow(["1.3", "A rising edge detected"])
table.AddRow(["3.8", "A falling edge detected"])

Parameters:

tableId: str | int | None = None¶: id to identify the table
headerValues: Iterable[str | int] | None = None¶: iterable with the entries of the table header

Returns:

the report table object

UpdateResultId(resultId: int) → None¶

Updates the result id for the current trace step.

The result id can be one of:

report.RESULT_ID_NONE
report.RESULT_ID_SUCCESS
report.RESULT_ID_INCONCLUSIVE
report.RESULT_ID_FAILED
report.RESULT_ID_ERROR

In contrast to SetResultId(), which sets the resultId directly, UpdateResultId() can only increase the resultId according to the following ordering:

RESULT_ID_NONE < RESULT_ID_SUCCESS < RESULT_ID_INCONCLUSIVE < RESULT_ID_FAILED < RESULT_ID_ERROR

Info

UpdateResultId() can bee seen as equivalent to SetResultId(max(resultId, GetResultId()))

..example:

report.UpdateResultId(report.RESULT_ID_SUCCESS)
...
report.UpdateResultId(report.RESULT_ID_FAILED)
...
report.UpdateResultId(report.RESULT_ID_SUCCESS)

report.GetResultId() # this will result in report.RESULT_ID_FAILED

Parameters:

resultId: int¶: the result id to set

SignalEvent¶

class traceAnalysisAPI.SignalEvent¶

A SignalEvent consists of a time stamp and multiple signal values. From the perspective of a TraceStep there is a constant stream of SignalEvent objects coming in, whose time stamps follow a strict partial order (that is, there are no duplicate time stamps).

GetSignal(name: str) → Signal | None¶

Returns the current signal (see Signal) for a given signal name (see TraceStep.DefineInSignals()) if it is contained in this SignalEvent.

Parameters:

name : string¶: the name of the desired signal

Return type:

Signal or None

GetSignals() → dict[str, Signal]¶

Returns a dictionary mapping signal names (see TraceStep.DefineInSignals()) to signals (see Signal)

Return type:: dict(string -> Signal)

GetTime() → float¶

Returns the time stamp of the SignalEvent

Return type:: float

GetValue(name: str) → float | dict[str, float | dict[str | None, float]] | None¶

Returns the current signal value (see Signal.GetValue()) for a given signal name (see TraceStep.DefineInSignals()) if it is contained in this SignalEvent.

Parameters:

name : string¶: the name of the desired signal

Return type:

float/string or None

Hold¶

class traceAnalysisAPI.Hold¶

GetSignal(name)¶

Returns the last known signal (see Signal) for a given signal name (see TraceStep.DefineInSignals()) if it is contained in this SignalEvent.

Parameters:

name : str¶: the name of the desired signal

Return type:

Signal or None

GetSignals()¶

Returns a dictionary mapping signal names (see TraceStep.DefineInSignals()) to the last known signals (see Signal)

Return type:: dict(str -> Signal)

GetValue(name)¶

Returns the last known signal value (see Signal.GetValue()) for a given signal name (see TraceStep.DefineInSignals()).

Parameters:

name : str¶: the name of the desired signal

Return type:

float or None

Parameters¶

TraceStep.parameters = {}¶

A dictionary mapping the names of the user defined trace step parameters to their values.

Example:

The tracestep has a parameter “Parameter_0” with integer value 100:

parameters["Parameter_0"] # returns 100 

Signal¶

class traceAnalysisAPI.Signal¶

A Signal object encapsulates the measurement value of one signal at a given point of time.

GetName() → str¶

Returns the name of the signal.

Return type:: string

GetPrevValue(restricted: bool = False) → object | None¶

Returns last known value of the signal before the current signal event.

Note

GetPrevValue() and GetValue() can return the same value,

if the signal has been measured with the same value twice in a row, which is not uncommon, especially for signals, that have been upsampled before trace analysis by means of value duplication

Parameters:

restricted : bool¶: if True only previous values within the current trigger range are returned, the parameter has only an effect at the beginning of a trigger range

Return type:

float or None

GetTime() → float | None¶

Returns the timestamp of the SignalEvent from which the signal stems.

Return type:: string

GetValue() → float | dict[str, float | dict[str | None, float]] | None¶

Returns the value of the signal.

Return type:: float

RecordingInfo¶

class traceAnalysisAPI.RecordingInfo¶

A RecordingInfo object contains information about the name, number, type and path of the underlying recording from which the signal stems.

GetFirstPath() → str | None¶

Returns the first path of the path list of the recordings or None, if the list is empty.

Returns:: path of the first recording, if exists

GetPath(idx=0) → str | None¶

Returns the path (or the first path if there is a list of paths) for the recording.

Returns:: The path

GetPathList() → list[str]¶

Returns the path list of the recordings.

Returns:: path list of the recordings

GetRecordingName() → str | None¶

Returns the name of the recording.

Returns:: the name of the recording

GetRecordingNumber() → int¶

Returns the number of the recording.

Returns:: the number of the recording (>=0, and < the total number of the associated recording group)

GetRecordingType() → str¶

Returns the type of the recording.

Returns:: type of the recording

GetStartTimeNs(*, synchronized: bool = True) → int | None¶

Returns the start time of the recording in nanoseconds since 1970-01-01T00:00:00Z.

This information is useful to calculate absolute timestamps, e.g.:

absoluteTimestampsInNs = int(relativeTimestampsInSeconds * 1e9) + startTimeNs

If the traces have not been synchronized, the value of the parameter synchronized does not matter. If the traces have been sychronized, this method should normally be called with synchronized=True (default) so that the start time is adjusted to the deltaT and the adjusted start time can just be added to the synchronized timestamps to get the absolute timestamps. However, if you want to get the real start time without any adjustments, you should call this method with synchronized=False.

Parameters:

synchronized: bool = True¶: If True, the start time is adjusted by the deltaT if available.

Returns:

start time in nanoseconds or None if the recording format does not support it

Raises:

ValueError – if the start time cannot be determined (e.g., empty file or missing metadata)

ReportTable¶

class traceAnalysisAPI.ReportTable¶

A ReportTable object represents a table in the test report.

AddRow(values: Iterable[str | int], resultId: int | None = None) → None¶

Appends a row to the table.

Parameters:

values: Iterable[str | int]¶: iterable with the entries for each column of the new row
resultId: int | None = None¶: the result id of the row

SetHeader(values: Iterable[str | int] | None) → None¶

Sets the table header.

Parameters:

values: Iterable[str | int] | None¶: iterable with the entries for each column of the table header

Range¶

class traceAnalysisAPI.Range¶

Class representing a range in the test report. An instance of Range is returned by the call of Report.Range(). To specify the range in more detail, it is possible to add spots and sub ranges as children to a range object.

Range(startTime, endTime, message='', resultId=None, additionalInfo=None)¶

Adds a sub range to the range.

Parameters:

startTime : float¶: timestamp at which the sub range begins
endTime : float¶: timestamp at which the sub range ends
message : string¶: a textual message describing the sub range
resultId : int¶: the verdict for the sub range
additionalInfo : list of strings¶: a list of additional information, that will be shown in the custom result columns (see Report.AddResultColumn())

Spot(time, message=None, resultId=None, additionalInfo=None)¶

Adds a signal spot to a range.

Parameters:

time : float¶: timestamp of the spot
message : string¶: a textual message describing the spot
resultId : int¶: the verdict for the spot
additionalInfo : list of strings¶: a list of additional information, that will be shown in the custom result columns (see Report.AddResultColumn())