Description

The ADTF Control handles everything about

remote accessing and controling an ADTF Session
scripting or interactive shell commands

as comfortable command line tooling.

Getting started

For any purpose, please execute the adtf_control with the option --help, which will give you an overview and example usage of available options and commands.

adtf_control
 
Usage:
        adtf_control --help
        adtf_control --version
        adtf_control [--settings <adtfsettingsfile>] [--connect [--url <url>]] ([--execute
                     <argument>...] | <scriptfile>)
 
        adtf_control [--settings <adtfsettingsfile>] [--launch <adtfsessionfile|adtfsystemfile>]
                     [--url <url>] [--launcher <launcher>] [--run] [--console] [--environment
                     <adtfenvironmentfile>] ([--execute <argument>...] | <scriptfile>)
 
        adtf_control [--settings <adtfsettingsfile>] [--url <url>] ([--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.
 
        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.
 
        Launching a new ADTF instance:
          --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.
 
        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.

Basics

ADTF Control can be used in two ways:

Interactive Mode - As soon as you type adtf_control -c into a terminal 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.

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.

Connect

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

adtf_control -c

Launch & Connect

To launch and connect to it, supply the --launch 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 (simlar to the ADTF Launcher calls).

adtf_control --launch "path/to/session/my_session.adtfsession" --run --console

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 --launcher adtf_profiling_enabled

All available launchers are defined in the configuration file $(ADTF_DIR/settings/adtf_control.adtfsettings.

Return codes

The ADTF Control returns the following exit codes:

Return code	Meaning
`0`	The execution was successful
`1`	The execution of the command returned an error
`2`	The command was not found

Interactive Mode

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.

␛[1;33mUnable to load settings file '/workspace/build/build/RelWithDebInfo/src/tools/settings/adtf_control.adtfsettings'
␛[0m
Return codes of executable:
 
     0: no error
    -1: command failed
    -2: invalid command
 
Supported input timestamp formats:
 
        ISO-8601 formats:
            e.g. 2024-09-26T23:59:59Z   -> Universal time UTC-0 (GMT). (preferred)
            e.g. 2024-09-26T23:59:59    -> Local time.
            e.g. 2024-09-26T23:59:59.123456789Z
        
            With timezone postfix 'Z' (default) means GMT time (UTC-0). Universal Coordinated Time.
            No timezone postfix 'Z' means your local timezone.
        
        number+unit format:
            with several unit postfixes = {h|hh|m|mm|min|s|ss|sec|ms|us|ns}
            e.g. 14.125h
            e.g. 8123ms
            e.g. 3.141s
        
Unsupported input timestamp formats:
 
        e.g. 9.12      (must have unit)
        e.g. T23:59:59 (no time only ISO timestamps)
        e.g. 1h 30ms   (no combined time fragments)
        
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>]
    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 <interval>] [--timeout <timeout>]
 
GRAPH:
    loadgraph <adtfgraphfile>
    loadgraphproperties <adtfpropertiesfile>
 
PLAYBACK:
    close 
    extract <file>...
    loopmode [<loopmode>]
    markers [--json]
    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 <recorder id>] [--time <time>] [--name <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 [--json] <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 [--json]
    listmacros [--json]
    microrunlevel|mrl [<micro runlevel>]
    processid 
    runlevel|rl [<runlevel>]
    startupcompleted 
    systemstatus [--json|-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.

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 -e exec commands.txt. For advanced scripting please use the scripting language of your choice (shell, python, ...) and execute commands via the -e switch. For more information on how to do this, please have a look at our Playback Scripting 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 -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 -c <URL> -e createreport > report.txt.

Table of Contents