Recorder

Table of Contents

• Plugin Information
• Plugin Versions
• Component Information
• Properties
• Runner Pins
• Input Binding Objects
• Dynamic Pins
• Required Interfaces
• Required/Optional Interfaces
• Recorder Basics
• Operation Modes
  • Write Through
    • Continuous Write Through [0]
    • Single Shot Write Through [1]
  • Memory Buffered
    • Single Shot Memory Buffered [2]
    • Continuous Memory Buffered [3]
• Attached Files
• Additional file support

Plugin Information

Plugin Filename	adtf_core.adtfplugin
Plugin Description	adtf_core.plugindescription
Plugin Name	ADTF Core Plugin
License	ADTF Subscription
Support Mail	support@digitalwerk.net
Homepage URL	https://adtf.dev

Plugin Versions

Plugin Version	3.99.99
Plugin File Version	1.0
adtf	3.99.99
adtf::ucom	3.1.0

Component Information

Name	Recorder
CID	adtfdat_file_recorder.streaming_sink.adtf.cid
Description	Use this streaming sink to store the measurement data in various formats (default is .adtfdat).
Type	Filter

Properties

Name	Value	Type	Description	Subproperties
asynchronous_processing	true	tBool	If activated, any file access will happen in a separate thread and the recorder is mostly non-blocking. Spawns an internal thread runner even if none is connected to the 'process_recording_data' runner port. Deactivate to ensure that the recorder will not maintain an internal queue of items, which may help with physical memory usage or faster-than-realtime transcoding scenarios.	Value Range: minimum = maximum = Filename Extension Filter:
attach_report	true	tBool	Whether or not to store a system report extension in each generated file.	Value Range: minimum = maximum = Filename Extension Filter:
attachment_configuration_file		cFilename	A configuration file that defines which files should be attached to the recordings. Please see the documentation for further information.	Value Range: minimum = maximum = Filename Extension Filter:
attachment_resolve_macros	false	tBool	Whether or not to resolve macros in the attached file configuration file (specified in attachment_configuration_file). Default is not to.	Value Range: minimum = maximum = Filename Extension Filter:
automatic_split_interval_seconds	0	tUInt32	When not equal to zero, split recordings after the given amount of seconds after a recording has been started.	Value Range: minimum = maximum = Filename Extension Filter:
cache_attachment_archive	true	tBool	Whether or not to cache the archive of attached file or recreate it each time a recording is closed. Default is to cache the archive.	Value Range: minimum = maximum = Filename Extension Filter:
default_description		cString	This description is stored in the file header.	Value Range: minimum = maximum = Filename Extension Filter:
diskspace_check_size	0	tUInt64	If less than the specified value of disk space [MB] remains, then the recording is stopped and the file is closed correctly.	Value Range: minimum = maximum = Filename Extension Filter:
file_format	4	tUInt32	Choose the ADTF DAT File format version: 'adtf3ns' stores timestamps with nanoseconds precision and is supported from ADTF 3.7 onwards. 'adtf3' stores timestamps with microseconds precision Mind that you need to choose appropriate serializations for each stream if you select 'adtf3'.	Value List: adtf3ns = 4 adtf3 = 3Value Range: minimum = maximum = Filename Extension Filter:
filename	$(ADTF_SESSION_DIR)/record_$(DATE)_$(TIME)$(ADTF_RECORDER_DEFAULT_FILENAME_EXTENSION)	cFilename	Filename of the measurement file to be saved.	Value Range: minimum = maximum = Filename Extension Filter: ADTF DAT file (.adtfdat),All files (*.)
filename_suffix_on_collision	_%03d	cString	The format of the suffix used when there is a filename collision with an existing file. Default is '_%03d'.	Value Range: minimum = maximum = Filename Extension Filter:
filename_suffix_on_split	split%03d	cString	The format of the suffix used for filename generation when a recording is split. Default is 'split%03d'.	Value Range: minimum = maximum = Filename Extension Filter:
follow_seconds	0	tUInt32	Recording time [sec] after the start (non-continuous)/stop (continuous) trigger (posttrigger).	Value Range: minimum = maximum = Filename Extension Filter:
history_seconds	0	tUInt32	Recording time [sec] before the start trigger (pretrigger).	Value Range: minimum = maximum = Filename Extension Filter:
keep_base_name_on_split	true	tBool	Use the name of the first file with the applied suffix when splitting files, without re-evaluating any macros.	Value Range: minimum = maximum = Filename Extension Filter:
log_channels/attachments/fatal_action	2	tUInt32	The default action when a fatal error is reported.	Value List: Stop session = 2 Shutdown ADTF = 3 Abort to crash handler = 4Value Range: minimum = maximum = Filename Extension Filter:
log_channels/attachments/log_level	35	tUInt8	The log level for this channel.	Value List: None = 0 Error = 10 Warning = 20 Info = 30 Detail = 35 Dump = 40 All = 255Value Range: minimum = maximum = Filename Extension Filter:
log_channels/attachments/recoverable_action	0	tUInt8	The action to perform when a recoverable error is reported.	Value List: Log only = 0 Treat as fatal = 1Value Range: minimum = maximum = Filename Extension Filter:
log_channels/default/fatal_action	2	tUInt32	The default action when a fatal error is reported.	Value List: Stop session = 2 Shutdown ADTF = 3 Abort to crash handler = 4Value Range: minimum = maximum = Filename Extension Filter:
log_channels/default/log_level	35	tUInt8	The log level for this channel.	Value List: None = 0 Error = 10 Warning = 20 Info = 30 Detail = 35 Dump = 40 All = 255Value Range: minimum = maximum = Filename Extension Filter:
log_channels/default/recoverable_action	0	tUInt8	The action to perform when a recoverable error is reported.	Value List: Log only = 0 Treat as fatal = 1Value Range: minimum = maximum = Filename Extension Filter:
log_channels/performance/fatal_action	2	tUInt32	The default action when a fatal error is reported.	Value List: Stop session = 2 Shutdown ADTF = 3 Abort to crash handler = 4Value Range: minimum = maximum = Filename Extension Filter:
log_channels/performance/log_level	35	tUInt8	The log level for this channel.	Value List: None = 0 Error = 10 Warning = 20 Info = 30 Detail = 35 Dump = 40 All = 255Value Range: minimum = maximum = Filename Extension Filter:
log_channels/performance/recoverable_action	0	tUInt8	The action to perform when a recoverable error is reported.	Value List: Log only = 0 Treat as fatal = 1Value Range: minimum = maximum = Filename Extension Filter:
memory_check_ratio	100	tUInt32	The percentage limit of physical memory used by the whole system which will be checked by ADTF. If the ratio will be exceeded, Recorder will not initialize or decrease the queues while running.	Value Range: minimum = maximum = Filename Extension Filter:
processor_id	adtfdat	cString	The processor ID of the ADTF processor that is used for storing the data.	Value Range: minimum = maximum = Filename Extension Filter:
recording_mode	0	tInt32	The mode of operation, please have a look at the entire Recorder documentation page for an in depth explanation of the different recording modes. Continuous recorders require manual stopping and support splitting. Single Shot recorders stop automatically and do not support manual stopping or splitting. Write Through type recorders write directly to the destination file. For history_seconds > 0 with processor_id != "adtfdat", the history is kept in a memory buffer until recording is started. Memory Buffered recorders buffer each file's content in RAM before committing to disk on stop or split.	Value List: Continuous Write Through = 0 Single Shot Write Through = 1 Single Shot Memory Buffered = 2 Continuous Memory Buffered = 3Value Range: minimum = maximum = Filename Extension Filter:
request_substreams	true	tBool	If activated, the recorder will request all substreams from all inputs. This will ensure, that all available data will be recorded. Mind that this can be millions of signals! To record only a subset of the available substreams use the "Substream Reducer" filter. If you want to selectively request substreams of a single input sample stream, deactivate this property and connect a "Substream Requestor" filter to the sample streams in parallel to the 'Recorder'. Please also keep in mind, that each parallel consumer which requests substreams will take effect and this content will be recorded as well.	Value Range: minimum = maximum = Filename Extension Filter:
start_recording_on_startup	false	tBool	Starts the recording when Runlevel Running is reached.	Value Range: minimum = maximum = Filename Extension Filter:
timebase_mode	0	tInt32	The time base used for file items in the produced datfile. In the default stream time mode, samples, triggers and stream type updates are recorded as-is with the current stream time at arrival on recorder. Playback will be based on the time of arrival at the recorder and sample timestamps can differ from stream time. In sample timestamp mode, samples are recorded with their sample timestamp. In this mode, the original triggers are not recorded, but instead generated as required when sample timestamps are incremented. This mode can be used only with a single input pin due to monotonicity requirements.	Value List: Use stream time at arrival at recorder = 0 Use sample timestamps only = 1Value Range: minimum = maximum = Filename Extension Filter:
trace_clocks	false	tBool	When true, clock offsets will be recorded in file extensions.	Value Range: minimum = maximum = Filename Extension Filter:

Runner Pins

Name	Activation Type	Data Triggered	Data Input	Thread Triggered	Thread Cyclic	Timer Triggered	Timer Interval	Description
process_recording_data	6	0		1	1	0	0	Connect a Thread Runner that will provide the context for writing all recording data to disk. If this is not connected, the recorder will create a thread on its own.

Input Binding Objects

Name	IID	Proxy OID	Description
control	recorder.ant.services.adtf.iid		Interface server for recording access

Dynamic Pins

Dynamic Input Pins	true
Dynamic Output Pins	false
Dynamic Input Binding Pins	false
Dynamic Output Binding Pins	false

Required Interfaces

IID
kernel.penguin.services.adtf.iid
reference_clock.vision.streaming.adtf.iid
adtf_file_objects.devil.services.adtf.iid

Required/Optional Interfaces

IID
rpc_object_server_registry.catwo.services.adtf.iid

Recorder Basics

For recording all required data sources the related sample streams have to be connected to the Recorder. The Recorder works with dynamic data binding which means that it generates a new Pin when it is requested and uses it exclusively for one connection. This information is stored as streaming information in the resulting file (filename).

Operation Modes

The operation mode is selected via the recording_mode property. Each mode combines two independent aspects:

• How recorded data reaches the disk – either Write Through or Memory Buffered.
• How recording is triggered and ended – either Continuous or Single Shot.

Both aspects can be combined, resulting in the four modes described below. Independently of the mode, a configurable amount of data preceding the start trigger can be retained as history (history_seconds, the pretrigger), and a configurable amount following the stop can be appended (follow_seconds, the posttrigger).

Mode	recording_mode	Triggering	Storage
Continuous Write Through	0	manual stop, supports splitting	written directly to disk
Single Shot Write Through	1	stops automatically	written directly to disk
Single Shot Memory Buffered	2	stops automatically	held in RAM, flushed on completion
Continuous Memory Buffered	3	manual stop, supports splitting	held in RAM, flushed on completion

Write Through

While recording, all data is written directly to the destination file. The pretrigger history (history_seconds) is buffered depending on the processor:

• For the adtfdat processor it is kept in a file based ring buffer.
• For all other adtf_file based processors it is kept in a memory buffer until recording starts, after which incoming data is written directly to the destination.

Continuous Write Through [0]

Recording is started with adtf::services::IRecorder::Start and continues until explicitly stopped with adtf::services::IRecorder::Stop. This mode supports manual splitting of the recording (adtf::services::IRecorder::Split).

Single Shot Write Through [1]

Recording is triggered with adtf::services::IRecorder::Start and continues for the optional follow time (follow_seconds), then stops automatically. Manual splitting and stopping are not supported.

Memory Buffered

The complete content of each file – both the pretrigger history (history_seconds) and the recorded data – is held in a memory based queue and flushed to disk only once all data for that file has been acquired (on stop or split). This is required to record with history_seconds > 0 for processors other than adtfdat.

Single Shot Memory Buffered [2]

Recording is triggered with adtf::services::IRecorder::Start and continues for the optional follow time (follow_seconds), then stops automatically. Manual splitting and stopping are not supported.

Continuous Memory Buffered [3]

Recording is started with adtf::services::IRecorder::Start and continues until explicitly stopped with adtf::services::IRecorder::Stop. This mode supports manual splitting of the recording (adtf::services::IRecorder::Split).

Warning

When using a Memory Buffered mode or while splitting files, the memory used to queue the data may exceed the available virtual memory. Size history_seconds and your data rate accordingly.

Note

You can also drive the Recorder via its RPC interface (adtf::remote::IRecorder::Start, adtf::remote::IRecorder::Stop, adtf::remote::IRecorder::Split). This is how our tools control the recording (e.g. ADTF Control).

Attached Files

The .adtfdat file can store additional meta content/files for resimulation purpose (e.g. databases for decoding). See Attached Files for further information how to use them.

Additional file support

The Recorder can be extended via processors from an adtffileplugin to directly write or convert samples to file formats different to adtfdat. The property processor_id specifies the used processor to handle the incoming stream. If none is set, the Recorder will take the processor of all loaded adtffileplugins which match the given file extension in the filename property.

You can use the context menu entry Select processor_id and create properties... of the Recorder to assist you selecting the processor and get the provided properties (if available for the processor_id).

Remarks

Please keep in mind that the available processors depending on which adtffileplugins have been specified in the system file of your session. The context menu dialog provides also a shortcut to System Editor to manage and select the available adtffileplugins. The mechanism is identical to handle adtffileplugin and their readers to extend the Player.

Please have a look at the example session How to record csv files for basic usage. After launching the session you can trigger the headless example recording by e.g. attaching with ADTF Control and the startrecording call (as well as stoprecording to finish the the recording).