The API documentation¶
This part of the documentation covers all the interfaces of trsfile.
Overview¶
This section gives an overview of the main classes and their descriptions.
-
trsfile.
open
(path, mode='r', **options)¶ Reads, modifies or creates a
TraceSet
with a specific storage engine (defaults toTrsEngine
).Parameters: - path (str) – path to the file or directory
- mode (str) – mode how to open the file or directory (same as the default
Python
open
) - options (dict(str, any)) – zero or more options that are passed down to the
TraceSet
and the storage engine. Available options can be found in the different storage engines. The storage engine can be selected withengine = 'TrsEngine'
(default value).
Returns: instance of a new or initialized
TraceSet
Return type:
-
trsfile.
trs_open
(path, mode='r', **options)[source]¶ Reads, modifies or creates a
TraceSet
with a specific storage engine (defaults toTrsEngine
).Parameters: - path (str) – path to the file or directory
- mode (str) – mode how to open the file or directory (same as the default
Python
open
) - options (dict(str, any)) – zero or more options that are passed down to the
TraceSet
and the storage engine. Available options can be found in the different storage engines. The storage engine can be selected withengine = 'TrsEngine'
(default value).
Returns: instance of a new or initialized
TraceSet
Return type:
-
class
trsfile.trace.
Trace
(sample_coding, samples, data=b'', title='trace', headers={})[source]¶ The
Trace
class behaves like alist
object were each item in the list is a sample of the trace.When a
Trace
is initialized the samples are (optionally) converted to anumpy.array
depending on the current type of the samples and the providedsample_coding
.
-
class
trsfile.trace_set.
TraceSet
(path, mode='r', **options)[source]¶ The
TraceSet
class behaves like alist
object were each item in the list is aTrace
.Storing the
TraceSet
requires knowledge on the format which is resolved through the usage of storage engines (Engine
).
-
class
trsfile.engine.trs.
TrsEngine
(path, mode='x', **options)[source]¶ This engine supports .trs files from Riscure as specified in the “Trace set coding” document in Inspector.
This engine supports the following options:
Option Description headers Dictionary containing zero or more headers, see trsfile.common.Header
live_update Performs live update of the TRS file every N traces. True for updating after every trace and False for never. padding_mode Padding mode to use. The supported values are: trsfile.common.TracePadding.NONE
andtrsfile.common.TracePadding.AUTO
(default)
-
class
trsfile.engine.file.
FileEngine
(path, mode='x', **options)[source]¶ This engine tries to save traces to disk in the most versatile and simple manner available. No known tools support this file format and serve only as an intermediate step to later convert it to a supported format.
This is can be useful when the trace length (number of samples) varies as this is often not supported in trace files.
After acquisition, the file can be converted to the proper format with the correct padding mode.
This engine supports the following options:
Option Description headers Dictionary containing zero or more headers, see trsfile.common.Header
-
class
trsfile.common.
Header
[source]¶ All headers that are currently supported in the .trs file format as defined in the inspector manual (2018). The storage engine shall try to always store all headers regardless if they are used or not. However, some file formats will have no way of storing arbitrary headers. As such, optional headers can be dropped.
Some headers can be used by
trsfile.trace_set.TraceSet
ortrsfile.trace.Trace
to augment their functionality. An example of this is thetrsfile.trace.Trace.get_key()
method.
-
class
trsfile.common.
SampleCoding
[source]¶ Defines the encoding of all the samples in the trace. Bit 4 specifies if it is a float (1) or an integer (0), bits 0 to 3 specifies the length of the value. Finally, bits 5-7 are currently reserved and set to 000.
This class is just a simple lookup table.
-
class
trsfile.common.
TracePadding
[source]¶ Defines the padding mode of the samples in each trace. This can be helpful when not all traces will be the same length. This can be set in
trsfile.open()
,trsfile.trs_open()
Mode Description NONE No padding will be used and an exception will be thrown when traces are not of the same length. PAD All traces will be padded with zeroes to the maximum trace length. TRUNCATE All traces will be truncated to the minimum trace length. AUTO Traces will be clipped or padded in the best possible way the storage engine supports. This could mean data is lost which because retroactive padding is not supported.
Common¶
-
class
trsfile.common.
Header
[source] Bases:
enum.Enum
All headers that are currently supported in the .trs file format as defined in the inspector manual (2018). The storage engine shall try to always store all headers regardless if they are used or not. However, some file formats will have no way of storing arbitrary headers. As such, optional headers can be dropped.
Some headers can be used by
trsfile.trace_set.TraceSet
ortrsfile.trace.Trace
to augment their functionality. An example of this is thetrsfile.trace.Trace.get_key()
method.-
ACQUISITION_COUPLING_OF_SCOPE
= 86¶
-
ACQUISITION_DEVICE_ID
= 89¶
-
ACQUISITION_FREQUENCY_FILTER
= 91¶
-
ACQUISITION_INPUT_IMPEDANCE
= 88¶
-
ACQUISITION_OFFSET_OF_SCOPE
= 87¶
-
ACQUISITION_RANGE_FILTER
= 92¶
-
ACQUISITION_RANGE_OF_SCOPE
= 85¶
-
ACQUISITION_TYPE_FILTER
= 90¶
-
DESCRIPTION
= 71¶
-
EXTERNAL_CLOCK_BASE
= 103¶
-
EXTERNAL_CLOCK_FREQUENCY
= 102¶
-
EXTERNAL_CLOCK_MULTIPLIER
= 98¶
-
EXTERNAL_CLOCK_PHASE_SHIFT
= 99¶
-
EXTERNAL_CLOCK_RESAMPLER_ENABLED
= 101¶
-
EXTERNAL_CLOCK_RESAMPLER_MASK
= 100¶
-
EXTERNAL_CLOCK_THRESHOLD
= 97¶
-
EXTERNAL_CLOCK_USED
= 96¶
-
GO_LAST_TRACE
= 106¶
-
INPUT_LENGTH
= 110¶
-
INPUT_OFFSET
= 107¶
-
KEY_LENGTH
= 112¶
-
KEY_OFFSET
= 109¶
-
LABEL_X
= 73¶
-
LABEL_Y
= 74¶
-
LENGTH_DATA
= 68¶
-
LOGARITHMIC_SCALE
= 78¶
-
NUMBER_SAMPLES
= 66¶
-
NUMBER_TRACES
= 65¶
-
NUMBER_VIEW
= 104¶
-
OFFSET_X
= 72¶
-
OUTPUT_LENGTH
= 111¶
-
OUTPUT_OFFSET
= 108¶
-
SAMPLE_CODING
= 67¶
-
SCALE_X
= 75¶
-
SCALE_Y
= 76¶
-
TITLE_SPACE
= 69¶
-
TRACE_BLOCK
= 95¶
-
TRACE_OFFSET
= 77¶
-
TRACE_OVERLAP
= 105¶
-
TRACE_TITLE
= 70¶
-
-
class
trsfile.common.
SampleCoding
[source] Bases:
enum.Enum
Defines the encoding of all the samples in the trace. Bit 4 specifies if it is a float (1) or an integer (0), bits 0 to 3 specifies the length of the value. Finally, bits 5-7 are currently reserved and set to 000.
This class is just a simple lookup table.
-
BYTE
= 1¶
-
FLOAT
= 20¶
-
INT
= 4¶
-
SHORT
= 2¶
-
-
class
trsfile.common.
TracePadding
[source] Bases:
enum.Enum
Defines the padding mode of the samples in each trace. This can be helpful when not all traces will be the same length. This can be set in
trsfile.open()
,trsfile.trs_open()
Mode Description NONE No padding will be used and an exception will be thrown when traces are not of the same length. PAD All traces will be padded with zeroes to the maximum trace length. TRUNCATE All traces will be truncated to the minimum trace length. AUTO Traces will be clipped or padded in the best possible way the storage engine supports. This could mean data is lost which because retroactive padding is not supported. -
AUTO
= 3¶
-
NONE
= 0¶
-
PAD
= 1¶
-
TRUNCATE
= 2¶
-
Trace¶
-
class
trsfile.trace.
Trace
(sample_coding, samples, data=b'', title='trace', headers={})[source] Bases:
object
The
Trace
class behaves like alist
object were each item in the list is a sample of the trace.When a
Trace
is initialized the samples are (optionally) converted to anumpy.array
depending on the current type of the samples and the providedsample_coding
.
TraceSet¶
Storage Engines¶
The TraceSet behaves like a list (it is a list of Traces). Each Trace also behaves like a list (it is a list of samples). This is all on a conceptual level and the storage engine specifies how this conceptual model is translated to a specific file format. This behavior also makes it easy to convert from any (supported) file format to another one.
TrsEngine¶
-
class
trsfile.engine.trs.
TrsEngine
(path, mode='x', **options)[source] Bases:
trsfile.engine.engine.Engine
This engine supports .trs files from Riscure as specified in the “Trace set coding” document in Inspector.
This engine supports the following options:
Option Description headers Dictionary containing zero or more headers, see trsfile.common.Header
live_update Performs live update of the TRS file every N traces. True for updating after every trace and False for never. padding_mode Padding mode to use. The supported values are: trsfile.common.TracePadding.NONE
andtrsfile.common.TracePadding.AUTO
(default)-
get_traces
(index)[source]¶ Retrieves zero or more traces from the trace set
Parameters: index (slice, int) – the slice or index that specifies which traces to get Returns: a list of zero or more traces from the trace set Return type: Trace, list[Trace]
-
is_closed
()[source]¶ Returns if the file backing the trace set is closed
Returns: True if the file is closed, otherwise False Return type: boolean
-
FileEngine¶
-
class
trsfile.engine.file.
FileEngine
(path, mode='x', **options)[source] Bases:
trsfile.engine.engine.Engine
This engine tries to save traces to disk in the most versatile and simple manner available. No known tools support this file format and serve only as an intermediate step to later convert it to a supported format.
This is can be useful when the trace length (number of samples) varies as this is often not supported in trace files.
After acquisition, the file can be converted to the proper format with the correct padding mode.
This engine supports the following options:
Option Description headers Dictionary containing zero or more headers, see trsfile.common.Header
-
INFO_FILE
= 'traceset.pickle'¶
-
close
()[source]¶ Closes the file backing the trace set. It also could perform the final writes to synchronize the file with the trace set.
Returns: None
-
del_traces
(index)[source]¶ Deletes zero or more traces from the trace set
Parameters: index (slice, int) – the slice or index that specifies which traces to delete Returns: None
-
get_traces
(index)[source]¶ Retrieves zero or more traces from the trace set
Parameters: index (slice, int) – the slice or index that specifies which traces to get Returns: a list of zero or more traces from the trace set Return type: Trace, list[Trace]
-
is_closed
()[source]¶ Returns if the file backing the trace set is closed
Returns: True if the file is closed, otherwise False Return type: boolean
-
Engine¶
-
class
trsfile.engine.engine.
Engine
(path, mode='x', **options)[source]¶ Bases:
object
-
close
()[source]¶ Closes the file backing the trace set. It also could perform the final writes to synchronize the file with the trace set.
Returns: None
-
del_traces
(index)[source]¶ Deletes zero or more traces from the trace set
Parameters: index (slice, int) – the slice or index that specifies which traces to delete Returns: None
-
get_traces
(index)[source]¶ Retrieves zero or more traces from the trace set
Parameters: index (slice, int) – the slice or index that specifies which traces to get Returns: a list of zero or more traces from the trace set Return type: Trace, list[Trace]
-
is_closed
()[source]¶ Returns if the file backing the trace set is closed
Returns: True if the file is closed, otherwise False Return type: boolean
-
is_read_only
()[source]¶ Returns if the trace set is read-only
Returns: True if the file is read-only, otherwise False Return type: boolean
-
read_only
= False¶
-
set_traces
(index, traces)[source]¶ Inserts zero or more traces into the trace set
Parameters: Returns: None
-