Introduction
This page covers the Trebuchet Configuration File.
Contents
Configuration File
Trebuchet populates it's application list and creates a listener for discovery data based on a JSON configuration file. On start up, the launcher looks for this file, called appConfiguration.json in the same folder as the Trebuchet executable.
If the app cannot parse the config file (usually due to a syntax error, or if the file is empty), no data will be displayed in the app:
A cause for this will usually be found in the log file, found in the Logs folder within the trebuchet_debug folder. The log file will usually indicate the exact location of any syntax errors. Another common error is to mistype the name of a field, resulting in an error message referencing a mis-matched constructor.
The config file itself consists of two sections: ConnectionConfig and TrebuchetApps, which are the Connection Details and the App Configuration respectively.
Example appConfiguration.json file:
{
"ConnectionConfig": {
"DiscoveryIPAddress": "239.69.69.69",
"DiscoveryInterface": "192.168.0.250",
"DiscoveryPublishPeriod": 5000,
"Port": 6317
},
"TrebuchetApps": [
{
"Name": "change this to name you like",
"Description": "A description of Trebuchet App",
"LaunchCommand": "example.exe",
"ExePath": "C:\\Apps\\example.exe",
"MutualExclusiveGroups": [],
"ParameterGroups": [],
"ExecutionEnv": ""
}
]
}
Connection Details - ConnectionConfig
The first section of an appConfiguration.json file - ConnectionConfig, instructs the app how to listen for radar discovery data for the Radar Discovery section. For example:
DiscoveryIPAddress: The multicast address from which to expect the messages.
DiscoveryInterface: The IP address of the receiving machine (i.e. the PC being used).
DiscoveryPublishPeriod: The time, in milliseconds, between publication of received discovery messages.
Port: The network port of the discovery radar units.
For example, a launcher used on a PC with a network IP address of 10.77.3.59:
"ConnectionConfig": {
"DiscoveryIPAddress": "239.69.69.69",
"DiscoveryInterface": "10.77.3.59",
"DiscoveryPublishPeriod": 5000,
"Port": 6317
}
App Configuration - TrebuchetApps
The second section of an appConfiguration.json file - TrebuchetApps, consists primarily of providing a name, description, app location, and parameters for the given app. At the top level, an app entry consists of the following fields:
Name: The name of the application.
Description: A short description of the application and what it does.
LaunchCommand: A command preceding the application, for example, Python3 to launch a Python3 file.
ExePath: The path to the executable or file to be executed.
ParameterGroups: Named groups of parameters to be passed to the application. See Parameters and Parameter Groups below for a more detailed explanation.
MutualExclusiveGroups: Mutually exclusive parameter groups, where only one parameter group can be used from this collection at any one time.
ExecutionEnv: The execution environment (i.e. working directory) used when launching the app.
When an app is launched, Trebuchet will use this information to construct a call to the executable/file and launch it as a new process. The design of the configuration attempts to make this process as flexible as possible, enabling you to launch (theoretically) any application available on your PC.
Using the configuration and the user’s input, the construct command will be of the form:
<LaunchCommand> <ExePath> <Selected MutuallyExclusiveGroup and Parameters>” {ParameterGroup.Name ParameterGroup.Parameters…}
Which will launch in the selection ExecutionEnv. Curly braces indicate that multiple parameter groups and their parameters are passed as arguments.
Parameters and Parameter Groups
An individual parameter consists of short and long names, whether or not they are required by the app, a default argument, and whether or not they have arguments. For example:
{
"ShortForm": "i",
"LongForm": "ipaddress",
"Required": false,
"DefaultValue": "127.0.0.1",
"HasArguments": true
}
Parameter groups consist of a name (which may be blank i.e. for global options) and any number of parameters. They are designed to represent named groups of arguments that may be passed to the app.
For example, an app may require IP addresses for both a server and a client. The program could have one option called “—server_ipaddress” and another called “—client_ipaddress”, but a near solution might be to prefix an “—ipaddress” option with server and radar, respectively. The resulting call to the command-line may then take the form:
relay.exe server --ipaddress 192.168.0.1 client --ipaddress 127.0.0.1
In this scenario, the app configuration could be instructed to take two groups, called server and client. This is the design utilised by Trebuchet.
With parameters, a parameter group may look like this:
{
"GroupName": "server",
"Parameters": [
{
"ShortForm": "i",
"LongForm": "ipaddress",
"Required": false,
"DefaultValue": "127.0.0.1",
"HasArguments": true
},
{
"ShortForm": "p",
"LongForm": "port",
"Required": false,
"DefaultValue": "6317",
"HasArguments": true
}
]
}
When displayed in the launcher, parameters are separated by their group name. Only the long form of the parameter name is given, and the DefaultValue field sets the value of the entry on start up. If the value of Required is set to true, then the launch button is disabled until that parameter is given a value.
Mutually Exclusive Groups
Some apps will have different parameters available depending on a keyword passed at the command-line.
For example, the Witness NavDataCapture Tool can be used to capture navigation data or set the range gain and offset of a radar. It cannot do both in the same instance, and modes are switched based on a keyword argument; each keyword has a different set of command-line options:
Witness.NavDataCapture.exe capture –ipaddress <ip address> --port <port> --rotations
or
Witness.NavDataCapture.exe setrange –gain <gain> --offset <offset> --ipaddress <ip address> --port <port>
Mutually exclusive parameter groups ensure that only one of these modes can be selected for a given instance. Within the configuration file, they are treated as a separate list to ParameterGroups:
When viewed in the UI, mutually exclusive groups are represented by a drop-down menu:
Once a group is selected, its constituent parameters are displayed.
Special Treatment of Ipaddress and Port Parameters
Above the App Parameters panel in Trebuchet is the Connection Details panel, which contains the Hostname and Port fields. These fields have some special characteristics unique to themselves.
If an app takes in parameters named ipaddress/ip_address and port as either global parameters (i.e. a blank group name) or as part of a Radar Group, then they will be translated to Hostname and Port in the radar. In other words, the values of Hostname and Port will always represent the radar’s connection details.
If you enter ipaddress and port as global options and do not see those options appear in the side panel, you should check to see if Hostname and Port are enabled in the connection panel. If the app cannot find these parameters in the config under the blank or Radar Group names, then these options will be greyed out.
This does not mean that all apps that connect to the radar may make use of this feature. For example, the Colossus Record and Playback tool only connects to the radar if it is taking a recording, so the ipaddress option is only available within the group Playback. Trebuchet will not recognise this as an app that can connect to the radar.
Related Information
-
Track Distribution Protocol (Witness 4.0)
-
Launching Trebuchet (Witness 4.0)
-
Configuring and Launching Apps for Trebuchet (Witness 4.0)
-
Trebuchet Configuration File (Witness 4.0)
-
Trebuchet Radar Discovery (Witness 4.0)
-
Trebuchet App Selection (Witness 4.0)
-
Trebuchet Launcher (Witness 4.0)
-
Camera Device Manager (Witness 4.0)