Introduction
Trebuchet is an application designed to launch other apps from the command-line, including scripts written in Python and PowerShell.
It uses a generic interface for defining launchable applications based on a configuration file which are then displayed in a simplified UI. The aim is to remove the need for interaction with the command-line when creating these apps, thereby making them easier to use for those not used to that interface.
Contents
App Selection
Upon launch, you are presented with a tiled list of available applications. The exact number of these depends on the configuration used. Each tile consists of the application's name and a short description of its function:
When an app is selected, the App Parameters panel is populated by text inputs representing the app’s command-line options. If the app has straightforward radar connection options, then the Hostname and Port fields become available in the Connection Details panel.
Once all required options are populated, the Launch button will become active. When clicked, it will launch a new command-line or PowerShell window with the app in question. The app’s launch path and parameters are defined in the launcher's configuration file.
Radar Discovery
The Radar Discovery tab displays radar available on the current network. It does this by listening to discovery data messages received from a network interface and defined in a config file.
Each radar is listed by it's serial number and has it's connection details listed. Clicking on the hostname of a given radar will take the user to that radars Vertex page. Some additional information is listed from the discovery data, including the number of azimuths, the range in metres, and whether Safeguard is enabled. The FFT Protocol and Point Data Output (PDO) modes are also given.
Limitations
While the launcher can be configured to launch practically any command-line app, there are some limitations to consider. These largely relate to the parameters themselves.
Parameters are not Typed
Currently, all parameters are treated as strings and there is no option otherwise. A consequence of this is that Boolean parameters (i.e. parameters where no argument is required, just a flag) cannot be changed into e.g. a checkbox. Instead, they are set by typing “true” into a text field.
No Input Validation
There is no way of doing input validation on any parameters. The app cannot know in advance the validation requirements for any given field.
Apps are Launched with all Parameters passed as Arguments
If a parameter is present in the config file, then it will be passed as an argument to the app when launching, regardless of its optionality.
The Witness.NavDataCapture Utility is an example of where this can cause an issue. It's SetRange option can be used to set the range gain, the range offset, or both. Trebuchet can only do both at once, which could become an issue if a user would like to keep the current setting for either.
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), 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 exe 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: Connection Details.
Connection Details
The first section of an appConfiguration.json file, ConnectionConfig, instructs the app on 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
Configuration of a single app consists primarily of providing a name, description, app location, and parameters for a given app. At the top level, an app entry consists of the 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 to you.
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.
Configuring and Launching an App
This section goes over two examples of adding an app to the configuration file: a Python script and an executable; both with arguments.
Python File
Within the IASDK, there are several example scripts for connecting to the radar and pulling some kind of data.
To start, it is recommended that the relevant files be copied into Trebuchet’s executable directory, in a folder called Apps. For this example, they will be placed in <Trebuchet exe directory/Apps/Python/.
Open the apps appConfiguration.json, and add a new entry to the TrebuchetApps list, in the following format:
"TrebuchetApps": [
<Current App list>,
{
"Name": "",
"Description": "",
"LaunchCommand": "",
"ExePath": "",
"ParameterGroups": [],
"MutualExclusiveGroups": [],
"ExecutionEnv": null
}
]
In this example, add the read_azimuth_of_fft_data.py script to the launcher. This is placed in Apps\Python\Python_radar_client\read_azimuth_of_fft_data.py. Set the name of the app to Read Single FFT Azimuth, and give an appropriate description. Since the “app” is a python script, we must provide a launch command. In this case, that command is python. Finally, set the ExePath field to Apps\\Python\\Python_radar_client\\read_azimuth_of_fft_data.py.
Note the double slash - this is required for Trebuchet to correctly parse the path.
The configuration entry will now look like this:
{
"Name": "Read Single FFT Azimuth",
"Description": "Connects to a radar and reads a single azimuth of data",
"LaunchCommand": "python",
"ExePath": "Apps\\Python\\Python_radar_client\\read_azimuth_of_fft_data.py”,
"ParameterGroups": [],
"MutualExclusiveGroups": [],
"ExecutionEnv": null
}
When the app is next launched, there will be a corresponding entry in the Trebuchet Launcher, but with no arguments:
You can add parameters (in parameter groups) to the ParameterGroups or MutaulExclusiveGroups lists, with the format:
“ParameterGroups”: [
…
{
"GroupName": "",
"Parameters": [
…
{
"ShortForm": "",
"LongForm": "",
"Required": false,
"DefaultValue": "",
"HasArguments": true
}
]
}
]
Where “…” indicates other elements that may be in the lists.
To find which parameters the script requires, you can run the script with the “-h” option, using python.
python
Apps\\Python\\python_radar_client\\usage_examples\\read_azimuth_of_fft_data.py
Alternatively, you can look inside the script to get the arguments:
This script only takes two arguments: ip_address and port. These are both global options, and are represented by putting them in a group with a blank group name. For example:
{
"GroupName": "",
"Parameters": [
{
"ShortForm": "i",
"LongForm": "ip_address",
"Required": false,
"DefaultValue": "192.168.0.1",
"HasArguments": true
},
{
"ShortForm": "p",
"LongForm": "port",
"Required": false,
"DefaultValue": "6317",
"HasArguments": true
}
]
}
So, the final configuration entry for this app looks like this:
{
"Name": "Read Single FFT Azimuth",
"Description": "Connects to a radar and reads a single azimuth of data",
"LaunchCommand": "python",
"ExePath": "Apps\\Python\\Python_radar_client\\read_azimuth_of_fft_data.py",
"ParameterGroups": [
{
"GroupName": "",
"Parameters": [
{
"ShortForm": "i",
"LongForm": "ip_address",
"Required": false,
"DefaultValue": "192.168.0.1",
"HasArguments": true
},
{
"ShortForm": "p",
"LongForm": "port",
"Required": false,
"DefaultValue": "6317",
"HasArguments": true
}
]
}
],
"MutualExclusiveGroups": [],
"ExecutionEnv": null
}
This creates an entry in the Trebuchet app:
As they are global fields, ip_address and port have been translated to Hostname and Port in the connection details pane. Their default values have also been ignored.
Pressing Launch on the app, with parameters filled out, will launch the python script in a new window.
Executable App
This example will go over adding the video_adjuster.exe application from the IASDK. First, copy the application executable into the Apps/Radar Utilities folder within the Trebuchet app directory.
In appConfiguration.json (also located in the trebuchet app directory), add a new, blank entry to the Trebuchet App List:
"TrebuchetApps": [
<Current App list>,
{
"Name": "",
"Description": "",
"LaunchCommand": "",
"ExePath": "",
"ParameterGroups": [],
"MutualExclusiveGroups": [],
"ExecutionEnv": null
}
]
Name this app Radar Video Adjuster, and set the ExePath to the location of the copied executable. Unlike the python example, no launch command is required:
{
"Name": "Radar Video Adjuster",
"Description": "Relays incoming 16-bit FFT messages as 8-bit",
"LaunchCommand": "",
"ExePath": "Apps\\Radar Utilities\\video_adjuster.exe",
"ParameterGroups": [],
"MutualExclusiveGroups": [],
"ExecutionEnv": null
}
Note the “//” in the ExePath. This is so that Trebuchet’s config parser can correctly interpret the file path.
When Trebuchet is next launched, it will contain the new app, with no parameters:
You can add parameters to the ParameterGroups or MutualExclusiveGroups lists in the configuration file for them to appear in the App Parameters panel. This will usually take the form:
“ParameterGroups”: [
…
{
"GroupName": "",
"Parameters": [
…
{
"ShortForm": "",
"LongForm": "",
"Required": false,
"DefaultValue": "",
"HasArguments": true
}
]
}
]
Where “…” represents other entries that may be in the list.
The radar video adjuster has two parameter groups: radar and server, where each group contains ipaddress and port parameters. This is represented in the config as follows:
"ParameterGroups": [
{
"GroupName": "radar",
"Parameters": [
{
"ShortForm": "i",
"LongForm": "ipaddress",
"Required": false,
"DefaultValue": "127.0.0.1",
"HasArguments": true
},
{
"ShortForm": "p",
"LongForm": "port",
"Required": false,
"DefaultValue": "6317",
"HasArguments": true
}
]
},
{
"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 the launcher next starts, the new Radar Video Adjuster output will look like this:
Note that the radar ipaddress and port parameters have been recognised as radar connection parameters, and so have been linked to the Hostname and Port fields.
Related Information
-
ClearWay™ System Design (Witness 4.0)
-
Getting Started (Witness 4.0)
-
ClearWay™ V4.7.x Release Notes (Witness 4.0)
-
ClearWay ™ (Products)
-
ClearWay™ V4.5.x Release Notes (Witness 4.0)
-
Track Distribution Protocol (Witness 4.0)
-
ClearWay™ Track Queries (Witness 4.0)
-
ClearWay™ V4.4.x Release Notes (Witness 4.0)
-
ClearWay™ V4.3.x Release Notes (Witness 4.0)
-
Final Steps (Witness 4.0)