.trsPython 中的Inspector Trace Set文件支持

Riscure Inspector 使用.trs文件格式从磁盘保存和读取跟踪。为了更好地帮助从第三方读取和写入跟踪集文件，Riscure 发布了这个 Python 库。

快速开始

该库支持.trs文件的读取和写入，但不（尚）支持修改现有.trs文件。theTraceSet和Traceclass 都模拟了 a 的所有功能list，所以尽情享受吧！

安装

这个库在Python 3 及更高版本的PyPi上可用。只需添加trsfile到您的requirements.txt或通过命令行安装它：

pip install trsfile

TRS 版本 2：跟踪（设置）参数

从 2.0 版开始，.trs 格式中添加了两个附加条款：跟踪集参数和跟踪参数。这些可用于以结构化但灵活的方式将补充（元）数据添加到您的跟踪集中。请注意，TRS V2 向后兼容 TRS V1。但是，正如可以预料的那样，使用 V2 之前的阅读器时将无法获得其他信息。

跟踪集参数

跟踪集参数是用户定义的键值对，可用于保存有关跟踪集的全局信息。可以使用以下类型的数据（另请参阅 trsfile.traceparameter）：

 BYTE:   1 byte integer
 SHORT:  2 byte integer
 INT:    4 byte integer
 FLOAT:  4 byte floating point
 LONG:   8 byte integer
 DOUBLE: 8 byte floating point
 STRING: UTF-8 encoded string value

每种类型都作为值的列表（数组）处理，包括单个值，因此请确保提供这些值。另请注意，除字节外的所有数值都被编码和解码为有符号值。

使用跟踪集参数

TraceSetParameterMap创建跟踪集时，可以通过创建对象来添加全局参数。此对象的行为类似于字典，尽管 trs 格式规定键必须始终是字符串，而值必须是任何受支持的参数类型。以下 python 代码显示了一个示例：

from trsfile.parametermap import TraceSetParameterMap
import trsfile.traceparameter as tp

parameters = TraceSetParameterMap()
parameters['BYTES'] =  tp.ByteArrayParameter([0, 1, 255])
parameters['SHORTS'] = tp.ShortArrayParameter([1, 1337, -32768, 32767]) 
parameters['INTS'] = tp.IntegerArrayParameter([42, int(1e6)]) 
parameters['FLOATS'] = tp.FloatArrayParameter([0.1, 0.2, 0.3]) 
parameters['LONGS'] = tp.LongArrayParameter([0x7fffffffffffffff])
parameters['DOUBLES'] = tp.DoubleArrayParameter([3.1415926535, 2.718281828])
parameters['STRINGS'] = tp.StringParameter('Lorem ipsum dolor')

跟踪参数

从用户的角度来看，跟踪参数的行为与跟踪集参数非常相似。它们是可以添加到每个跟踪的值，描述了跟踪之间可能变化的特定值。可以使用的数据类型与跟踪集参数相同。但是，有几个细节是不同的：

1. 由于 trs 文件的存储方式，每个跟踪的添加信息的长度必须相同。这意味着添加到跟踪集中的第一条跟踪指示数组和字符串的长度。如果稍后添加更长的字符串，则会导致跟踪集损坏。
2. 每个参数的长度在创建时保存在标头中，名为TraceParameterDefinitionMap. 该结构用于读取迹线以确定包含数据的结构，因此必须与实际迹线参数一致才能创建有效的迹线集。此信息不会添加到各个跟踪本身。
3. 展望未来，将有用于标记重要信息的预定义标签：
   • SAMPLES：另一种保存跟踪样本的方法。这可能会在未来取代标题数据样本的预定义跟踪结构。
   • TITLE：另一种保存跟踪标题的方法。这可能会在未来取代标题数据样本的预定义跟踪结构。

使用跟踪参数

TraceParameters创建跟踪时，可以通过创建对象来添加局部参数。以下 java 代码显示了一个示例：

from trsfile import Trace, SampleCoding
from trsfile.parametermap import TraceParameterMap
import trsfile.traceparameter as tp

parameters = TraceParameterMap()
parameters["BYTE"] = tp.ByteArrayParameter([1, 2, 4, 8])
parameters["INT"] = tp.IntegerArrayParameter([42])
parameters["DOUBLE"] = tp.DoubleArrayParameter([3.14, 1.618])
parameters["STRING"] = tp.StringParameter("A string")
Trace(SampleCoding.FLOAT, list(range(100)), parameters, "trace title")

注意前面提到的TraceParameterDefinitionMap必须创建和上面的参数一致并添加到headers中：

from trsfile import Header, trs_open
from trsfile.parametermap import TraceParameterDefinitionMap
from trsfile.traceparameter import ParameterType, TraceParameterDefinition

definitions = TraceParameterDefinitionMap()
definitions["BYTE"] = TraceParameterDefinition(ParameterType.BYTE, 4, 0)
definitions["INT"] =  TraceParameterDefinition(ParameterType.INT, 1, 4)
definitions["DOUBLE"] = TraceParameterDefinition(ParameterType.DOUBLE, 1, 8)
definitions["STRING"] = TraceParameterDefinition(ParameterType.STRING, 8, 16)

with trs_open('trace-set.trs', 'w',
              headers = {Header.TRACE_PARAMETER_DEFINITIONS: definitions}):
    pass

有关使用参数创建跟踪集的更详细示例，请参见下文。

读取.trs文件

import trsfile

with trsfile.open('trace-set.trs', 'r') as traces:
	# Show all headers
	for header, value in traces.get_headers().items():
		print(header, '=', value)
	print()

	# Iterate over the first 25 traces
	for i, trace in enumerate(traces[0:25]):
		print('Trace {0:d} contains {1:d} samples'.format(i, len(trace)))
		print('  - minimum value in trace: {0:f}'.format(min(trace)))
		print('  - maximum value in trace: {0:f}'.format(max(trace)))

创建.trs文件

import random, os
from trsfile import trs_open, Trace, SampleCoding, TracePadding, Header
from trsfile.parametermap import TraceParameterMap, TraceParameterDefinitionMap
from trsfile.traceparameter import ByteArrayParameter, ParameterType, TraceParameterDefinition

with trs_open(
		'trace-set.trs',                 # File name of the trace set
		'w',                             # Mode: r, w, x, a (default to x)
		# Zero or more options can be passed (supported options depend on the storage engine)
		engine = 'TrsEngine',            # Optional: how the trace set is stored (defaults to TrsEngine)
		headers = {                      # Optional: headers (see Header class)
			Header.TRS_VERSION: 2,
			Header.SCALE_X: 1e-6,
			Header.SCALE_Y: 0.1,
			Header.DESCRIPTION: 'Testing trace creation',
			Header.TRACE_PARAMETER_DEFINITIONS: TraceParameterDefinitionMap(
				{'parameter': TraceParameterDefinition(ParameterType.BYTE, 16, 0)})
		},
		padding_mode = TracePadding.AUTO,# Optional: padding mode (defaults to TracePadding.AUTO)
		live_update = True               # Optional: updates the TRS file for live preview (small performance hit)
		                                 #   0 (False): Disabled (default)
		                                 #   1 (True) : TRS file updated after every trace
		                                 #   N        : TRS file is updated after N traces
	) as traces:
	# Extend the trace file with 100 traces with each 1000 samples
	traces.extend([
		Trace(
			SampleCoding.FLOAT,
			[random.uniform(-255, 255) for _ in range(0, 1000)],
			TraceParameterMap({'parameter': ByteArrayParameter(os.urandom(16))})
		)
		for _ in range(0, 100)]
	)

	# Replace 5 traces (the slice [0:10:2]) with random length traces.
	# Because we are creating using the TracePadding.PAD mode, all traces
	# will be clipped or padded on the first trace length
	traces[0:10:2] = [
		Trace(
			SampleCoding.FLOAT,
			[random.uniform(0, 255) for _ in range(0, random.randrange(1000))],
			TraceParameterMap({'parameter': ByteArrayParameter(os.urandom(16))}),
			title = 'Clipped trace'
		)
		for _ in range(0, 5)
	]

	# Adding one Trace
	traces.append(
		Trace(
			SampleCoding.FLOAT,
			[random.uniform(-255, 255) for _ in range(0, 1000)],
			TraceParameterMap({'parameter': ByteArrayParameter(os.urandom(16))})
		)
	)

	# We cannot delete traces with the TrsEngine, other engines do support this feature
	#del traces[40:50]

	# We can only change headers with a value that has the same length as the previous value
	# with the TrsEngine, other engines can support dynamically adding, deleting or changing
	# headers.
	#traces.update_header(Header.LABEL_X, 'Time')
	#traces.update_header(Header.LABEL_Y, 'Voltage')
	#traces.update_header(Header.DESCRIPTION, 'Traces created for some purpose!')

	print('Total length of new trace set: {0:d}'.format(len(traces)))

从一种类型转换TraceSet为另一种类型

import trsfile

with \
	trsfile.open(
		'trace-set',                  # Previously create trace set
		'r',                          # Read only mode
		engine='FileEngine'           # Using the FileEngine
	) as traces, \
	trsfile.open(                     # Note: TrsEngine is the default
		'trace-set.trs',              # Name of the new trace set
		'w',                          # Write mode
		headers=traces.get_headers()  # Copy the headers
	) as new_traces:
	new_traces.extend(traces)         # Extend the new trace set with the
	                                  # traces from the old trace set

文档

完整的文档可在Read the Docsdocs上的文件夹中找到，其中包含可读版本。

测试

该库支持 Pythonunittest模块，可以使用以下命令执行测试：

python -m unittest

执照

BSD 3 条款明确许可