This guide covers the control commandline tool. After reading this guide, you will know:
ADTF Control can be used in two ways:
adtf_control.exe -cinto 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).
adtf_control.exe -e exec commands.txt.
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.
adtf_control.exe --help into a console to get an idea how to invoke the ADTF Control:
adtf_control Usage: adtf_control -h adtf_control -v adtf_control [-s <adtfsettingsfile>] [-c [-u <url>]] ([-e <argument>...] | <scriptfile>) adtf_control [-s <adtfsettingsfile>] [-l <adtfsessionfile|adtfsystemfile>] [-u <url>] [--launcher <launcher>] [-r] [--console] [--environment <adtfenvironmentfile>] ([-e <argument>...] | <scriptfile>) adtf_control [-s <adtfsettingsfile>] [-u <url>] ([-e <argument>...] | <scriptfile>) Options: -h, --help Print the usage info and quit. -v, --version Print the version information and quit. -s, --settings <adtfsettingsfile> Load custom adtfsettings file. If not specified, ADTF Control will search for adtf_control.adtfsettings in working directory, afterwards in <ADTF_DIR>/settings. Connecting to a running ADTF instance: -c, --connect Connect to an ADTF instance on the default URL ('http://localhost:8000'). -u, --url <url> Connect to an ADTF system using the given URL for RPC communication. Launching a new ADTF instance: -l, --launch <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. -u, --url <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. -r, --run 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. Scripting: -e, --execute <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:
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
--run parameter. To see log messages in the console use the
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.
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 'W:\conan_build\Release\src\tools\adtfcontrol\settings/adtf_control.adtfsettings' Available commands by groups: CLOCK: adtftime clocks streamtime COMMON: connect [<url>] disconnect exec <script file> help [<command>] launch <adtfsessionfile|adtfsystemfile> [--control-url <url>] [--launcher <launcher>] [-a] [--console] [--environment <adtfenvironmentfile>] quit shutdown sleep <duration> squit workingdir [<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>] [<expected value index>] [<polling interval>] [<timeout>] 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 [<recorder id> [<file>]] startrecording [<recorder id> [<file>]] stoprecording [<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 SESSION: activefiltergraph [<filtergraph>] activestreaminggraph [<streaminggraph>] getprop <session object> <property name> getproptype <session object> <property name> kernelobjects listprops [-xml] <session object> sessionname sessionobjects setprop <session object> <property name> <property value> SYSTEM: createreport info isalive listcomponents [--xml] processid runlevel [<runlevel>] systemstatus [--xml|-b] TOOLS: launchers logview [<url>] profiler statusmonitor [<url>]
For more details about a certain command type
help <command>, for example:
adtf> help setprop SYNOPSIS: setprop <SESSION_OBJECT> <PROPERTY_NAME> <PROPERTY_VALUE> DESCRIPTION: Sets the value of a given property for a specific session object.
The ADTF Control has support to configure different launcher commands that can be used either with
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
The ADTF Control returns the following exit codes:
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
adtf_control.exe -e exec commands.txt. For advanced scripting please use the scripting language of your choice and execute commands via the
-eswitch. For more information on how to do this, please have a look at our Playback Scripting Example.
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.
There is one command which collects a set of useful commands, called
It is very helpful to gather a bunch of information about a running ADTF System, for example
listcomponents or automatic combinations like
listprops for each item from
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.
adtf_control.exe -c -e createreport > report.txtwill 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
You need more convenience? Here you go: ADTF GUI Control - The user interface for the control.