DTrackCLI: Command Line Interface for DTrack2 and DTRACK3
---------------------------------------------------------

Version: 1.1.0

Copyright (c) 2016-2023 Advanced Realtime Tracking GmbH & Co. KG

This program is distributed under the BSD 3-clause license.
You can modify sources and/or include sources or binaries into your own applications
(for details see 'license.txt').

If you are interested in the source code (C++) please contact A.R.T.

-------------------------------------------------------------------------------

GENERAL:

How to use DTrackCLI:

To start the program open your command-line interface, change to the folder
containing the DTrackCLI file and run it. The correct usage of the program 
will be displayed including all possible arguments:

Usage: DTrackCLI <ATC hostname or ip> [<action> ...]
Apply an action to the ART Controller (ATC) specified by ACTION(s)
with <ATC hostname or ip> being either the IP address or the
hostname of the ART Controller e.g.: atc-123456 or 12.34.56.78
Available actions:
  -meastart                   start measurement
  -meastop                    stop measurement
  -shutdown                   shut down the ART Controller
  -get <parameter>            read and display the value of a DTrack2/DTRACK3 parameter
  -set <parameter> <value>    change the value of a DTrack2/DTRACK3 parameter
  -cmd <dtrack2 command>      send DTrack2/DTRACK3 command directly
  -f <filename>               read and execute DTrack2/DTRACK3 commands from a file
  -h, --help, /?              display this help

It is possible to string together multiple actions which will be executed one after the other:
$ DTrackCLI <ATC hostname or ip> -set <parameter> <value> -get <parameter> -f <filename>

Examples:
$ DTrackCLI 12.34.56.78 -meastart
$ DTrackCLI atc-123456 -get "camera number_of_cameras"
$ DTrackCLI 12.34.56.78 -get "camera number_of_cameras" -cmd "dtrack2 tracking start"

NOTE: Do not forget to use quotation marks, if DTrack2/DTRACK3 parameter names, values or
      commands contain white spaces!
NOTE: If DTrack2/DTRACK3 values or commands contain quotation marks, you need to escape
      them with a backslash ( \" )!
NOTE: Not all commands are available during an active measurement!

-------------------------------------------------------------------------------

FILES:

In a file each DTrack2/DTRACK3 command has to be written in an extra line (example):

dtrack2 set parameter value
dtrack2 get parameter
set parameter value
get parameter
tracking start
dtrack2 tracking stop

("dtrack2" at the beginning of each line is optional)

-------------------------------------------------------------------------------

INTERACTIVE MODE:

When starting the program without any actions specified:

$ DTrackCLI <ATC hostname or ip>

the program will enter an interactive mode. In interactive mode it is waiting for
the input of single DTrack2 commands (typed one by one directly into the terminal).
Press "Ctrl + C" to exit the program.
This enables the possibility to pipe actions into DTrackCLI by using the pipe
command in the terminal or by creating a batch file which pipes the actions.
This works slightly different depending on the operating system.

-------------------------------------------------------------------------------

WINDOWS PIPES:

Note: In order to start DTrackCLI in Windows, the DTrackCLI command has to be
"DTrackCLI.exe" (e.g.: "DTrackCLI.exe <ATC hostname or ip> -meastart").

Example for a pipe in the command line:

$ echo dtrack2 get parameter| DTrackCLI.exe <ATC hostname or ip>


Example of a batch file:

@Echo off
echo dtrack2 set parameter value| DTrackCLI.exe <ATC hostname or ip>
echo dtrack2 get parameter| DTrackCLI.exe <ATC hostname or ip>
echo set parameter value| DTrackCLI.exe <ATC hostname or ip>
echo get parameter| DTrackCLI.exe <ATC hostname or ip>

("dtrack2" at the beginning of each line is optional)

-------------------------------------------------------------------------------

LINUX PIPES:

Note: In order to start DTrackCLI in Linux, the DTrackCLI command has to be
"./DTrackCLI" (e.g.: "./DTrackCLI <ATC hostname or ip> -meastart").

Example for a pipe in the command line:

$ echo dtrack2 get parameter | ./DTrackCLI <ATC hostname or ip>


Example of a bash shell script:

#!/bin/bash
./DTrackCLI <ATC hostname or ip> <<EOF
dtrack2 set parameter value
dtrack2 get parameter
set parameter value
get parameter
EOF

("dtrack2" at the beginning of each line is optional)

