ADTF3 Guides - ADTF Control

The ADTF Control

This guide covers the control commandline tool. After reading this guide, you will know:

What the control is and what it does
How to operate the control

Some basics

ADTF Control can be used in two ways:

Interactive Mode - As soon as you type adtf_control.exe -c into a console followed by Enter (presumed there is an ADTF Launcher you can connect to) you are in interactive mode where you can issue ADTF commands in a manner known as read–eval–print loop (REPL).
Scripting Mode - In this mode you specify the commands you want to issue in a file (e.g. commands.txt) and type adtf_control.exe -e exec commands.txt.

Establish a connection

You can imagine the control as a kind of generic remote control, like the one you are using for your TV but instead of controlling a TV you control an ADTF System by sending specific commands. Depending on where the ADTF Launcher was started, this may be a real remote communication over a network. Type adtf_control.exe --help into a console to get an idea how to invoke the ADTF Control:

        
adtf_control

Usage:
        adtf_control --help [--fep-participant-count <fep_participant_count>] [--fep-timeout
                     <fep_system_discovery_timeout>] ([--execute <argument>...] | <scriptfile>)

        adtf_control --version [--fep-participant-count <fep_participant_count>] [--fep-timeout
                     <fep_system_discovery_timeout>] ([--execute <argument>...] | <scriptfile>)

        adtf_control [--settings <adtfsettingsfile>] [--connect [--url <url>]]
                     [--fep-participant-count <fep_participant_count>] [--fep-timeout
                     <fep_system_discovery_timeout>] ([--execute <argument>...] | <scriptfile>)

        adtf_control [--settings <adtfsettingsfile>] [--launch <adtfsessionfile|adtfsystemfile>]
                     [--url <url>] [--launcher <launcher>] [--run] [--console] [--environment
                     <adtfenvironmentfile>] [--fep-participant-count <fep_participant_count>]
                     [--fep-timeout <fep_system_discovery_timeout>] ([--execute <argument>...] |
                     <scriptfile>)

        adtf_control [--settings <adtfsettingsfile>] [--url <url>] [--fep-participant-count
                     <fep_participant_count>] [--fep-timeout <fep_system_discovery_timeout>]
                     ([--execute <argument>...] | <scriptfile>)

Options:
        --help, -h  Print the usage info and quit.
        --version, -v
                    Print the version information and quit.

        --settings, -s <adtfsettingsfile>
                    Load custom adtfsettings file. If not specified, ADTF Control will search for
                    adtf_control.adtfsettings in working directory, afterwards in
                    <ADTF_DIR>/settings.

        Launching a new ADTF instance:

          Connecting to a running ADTF instance:
            --connect, -c
                    Connect to an ADTF instance on the default URL ('http://localhost:8000').

            --url, -u <url>
                    Connect to an ADTF system using the given URL for RPC communication.

          --launch, -l <adtfsessionfile|adtfsystemfile>
                    Launch an ADTF system with the given session or system file. If you do not
                    specify a URL with -u, the default URL ('http://localhost:8000') will be used.

          --url, -u <url>
                    The URL will be passed on to the launched ADTF system and used to connect to it.

          --launcher <launcher>
                    Use the given launcher. If not specified the first one in the
                    adtf_control.adtfsettings file will be used.

          --run, -r If used in conjunction with --launch, will pass the --run flag on to the
                    launcher.

          --console Will forward the --console flag to the launcher.
          --environment <adtfenvironmentfile>
                    Specify an ADTF environment file that should be passed on to the launcher.

        --fep-participant-count <fep_participant_count>
                    If url passed with --control-url starts with 'fep', the number of expected FEP
                    Participants should be given here

        <fep_system_discovery_timeout>
                    If url passed with --control-url starts with 'fep', a FEP System discovery
                    timeout (milliseconds) should be given here.

        Scripting:
          --execute, -e <argument>
                    Execute a command and quit. All arguments following will be interpreted as the
                    command.

          <scriptfile>
                    If specified, execute the script and quit.

To connect the control with an already running ADTF System use this command:

adtf_control.exe -c

To start an ADTF System implicitly and connect to it, supply the --launch "path\to\session\file" parameter with an ADTF Session file to load. To get the started ADTF System into runlevel Running add the --run parameter. To see log messages in the console use the --console parameter.


adtf_control.exe --launch "../src/examples/projects/adtf_example_project/adtfsessions/demo_playback.adtfsession" --run --console

As you can see, this call is very similar to the launcher call that starts an ADTF System from the previous chapter.

Available commands

As soon as you are connected, type help to see an overview of all commands you can send to the ADTF System. ADTF Control also provides auto-completion for available commands and arguments.

                
Unable to load settings file '/workspace/build/build/RelWithDebInfo/src/tools/settings/adtf_control.adtfsettings'

Return codes of executable:

	 0: no error
	-1: command failed
	-2: invalid command

Available commands (with their aliases) by groups:

CLOCK:
	adtftime 
	clocks 
	streamtime|st 

COMMON:
	connect|c [<url>]
	disconnect 
	exec <script file>
	help|h [<command>]
	launch|l <adtfsessionfile|adtfsystemfile> [--control-url <url>] [--launcher <launcher>] [-a] [--console] [--environment <adtfenvironmentfile>] [--fep-participant-count <fep_participant_count>] [--fep-timeout <fep_system_discovery_timeout>]
	quit|q 
	shutdown 
	sleep <duration>
	squit|sq 
	workingdir|wd [<directory>]

EVENTS:
	createeventbuffer <session object> <event type>
	createeventbufferraw <session object> <struct name> <struct ddl>
	events <buffer id>
	releasealleventbuffers 
	releaseeventbuffer <buffer id>
	waitevent <buffer id> [<expected value>] [--index <value index>] [--interval <milliseconds>] [--timeout <milliseconds>]

FEP:
	fep::configuretimingcontinuous|fctmc <master_participant_name> [--sync_cycle_time <time in ms>] [--master_clock <name>]
	fep::configuretimingdiscrete|fctmd <master_participant_name> [--cycle_time <time in ms>] [--master_clock <name>] [--time_factor <factor as float>]
	fep::configuretimingplayer|fctmp <master_participant_name>
	fep::connectsystem|fcs <fep_system_name> [<expected_participant_count>] [<discovery_timeout>]
	fep::discoverallsystems|fdas [<expected_participant_count> [<discovery_timeout>]]
	fep::discoversystem|fds <fep_system_name> [<expected_participant_count>] [<discovery_timeout>]
	fep::getconnectedsystem|fgcs 
	fep::getprop|fgp <fep_participant_name> <property_name>
	fep::getprops|fgps <fep_participant_name>
	fep::getsignals|fgs 
	fep::setprop|fsp <fep_participant_name> <property_name> <property_value>
	fep::systemrunlevel|fsrl [<fep_runlevel>]

GRAPH:
	loadgraph <adtfgraphfile>
	loadgraphproperties <adtfpropertiesfile>

PLAYBACK:
	close 
	extract <file>...
	loopmode [dontloop|seektostart|changerunlevel]
	markers 
	open <file>...
	pause 
	play 
	playbackfiles 
	playbackspeed [<speed>]
	playbackstate 
	playbacktime 
	seek <timestamp>
	seekchunk <chunk index>
	seekmarker <name> [<occurence>]
	seeknext [<name> [<count>]]
	seekprev [<name> [<count>]]
	step [<count>] [--do-not-wait] [--backwards] [--samples|--types|--triggers]

RECORDING:
	addmarker [<recorder_id> [<time>] [<name>]]
	drophistory [<recorder id>]
	recorderids 
	recorderstate [<recorder id>]
	recordingfile [<recorder id>]
	splitrecording|d [<recorder id> [<file>]]
	startrecording|a [<recorder id> [<file>]]
	stoprecording|s [<recorder id> [<file>]]

RPC:
	getinterfacedefinition <rpc object>
	rpc <rpc object> <method name> [<parameter name> <parameter value>]...
	rpcjson <rpc object> <method name> [<json parameter string>]
	rpcmethodparams <rpc object> <method name>
	rpcmethods <rpc object>
	rpcnotify <rpc object> <method name> [<parameter name> <parameter value>]...
	rpcnotifyjson <rpc object> <method name> [<json parameter string>]
	rpcobjects 

RUNNER:
	triggerrunner <runner id> [--sync] [<timestamp>]

SESSION:
	activefiltergraph [<filtergraph>]
	activestreaminggraph [<streaminggraph>]
	deinit 
	getgraphobjectinfo [--json] <session graph object>
	getgraphobjects 
	getgraphobjectsinfo [--json]
	getgraphobjectstate <session object>
	getprop <session object> <property name>
	getproptype <session object> <property name>
	init 
	kernelobjects 
	listprops [-xml] <session object>
	run 
	sessionname 
	sessionobjects 
	setgraphobjectstate <session graph object> <session graph object state>
	setprop <session object> <property name> <property value>
	stop 

SYSTEM:
	createreport 
	info 
	isalive 
	listcomponents [--xml]
	listmacros [--xml]
	microrunlevel|mrl [<micro runlevel>]
	processid 
	runlevel|rl [<runlevel>]
	startupcompleted 
	systemstatus [--xml|-b]

TOOLS:
	launchers 
	logview [<url>]
	profiler 
	statusmonitor [<url>]

For more details about a certain command type help <command>, for example:

                
adtf> help workingdir

HELP FOR COMMAND "workingdir":

Description:
        Sets the working directory or returns the current working directory if no parameter is given.

Output:
        [string] current dir

Usage:
        workingdir [<directory>]

Options:
        <directory> If specified, changes the current working directory of the connect ADTF instance.

Configuring different Launchers

The ADTF Control has support to configure different launcher commands that can be used either with the launch command or the --launcher command line argument. Let's say you want to do some profiling, you can enable it by using a different ADTF Launcher: adtf_control.exe --launcher adtf_profiling_enabled. All available launchers are defined in the configuration file adtf_control.adtfsettings.

The ADTF Control returns the following exit codes:

0 - The execution was successful
1 - The execution of the command returned an error
2 - The command was not found

Scripting Mode

The ADTF Control supports very basic scripting. You can create a file (e.g. commands.txt) where each line contains a command:

# Comments are prefixed with a hash and
# start at the beginning of a line
# whitespace is ignored
connect http://localhost:8000
runlevel running
sleep 10000000
runlevel filtergraph

After that try to run adtf_control.exe -e exec commands.txt. For advanced scripting please use the scripting language of your choice and execute commands via the -e switch. For more information on how to do this, please have a look at our Playback Scripting Example.

Event Handling

Due to the asynchronous nature of the RPC communication, event handling can only be performed via polling. To do so, use the "createeventbuffer" and "createeventbufferraw" commands, that will create a buffer within the ADTF System where the specified events will be stored until you retrieve them via the "events" command. Since each event source uses its own event data structure, the structures have to be described via DDL. The "createeventbuffer" command provides a few predefined definitions for convinience, please take a look at the commands documentation within adtf_control. You can use the "waitevent" command to continuously poll for a specific event.

Report Command

There is one command which collects a set of useful commands, called createreport. It is very helpful to gather a bunch of information about a running ADTF System, for example systemstatus, listcomponents or automatic combinations like listprops for each item from sessionobjects.

This could be a good overview for yourself as well as as additional and required information for the support team in case of troubles during runtime.

Use standard piping mechanism to redirect the output to a report file, e.g. using adtf_control.exe -c -e createreport > report.txt will attach to default url and create a report.txt file. Of course you can attach to any other ADTF System, as you already know by using adtf_control.exe -c <URL> -e createreport > report.txt

Where to go next?

You need more convenience? Here you go: (Deprecated) ADTF GUI Control - The user interface for the control.