In addition to the documentation included on this page below, the following reference files are available:
Whenever you run TWRTrainer, the first thing you see is the "Load Airport File" window. Since this is your first
time running TWRTrainer, you may not have any airport files yet. Just press Esc to
close the window. You can now configure TWRTrainer. On the Settings menu, there are three items you need to configure. They
are "Server", "CID", and "Password". For the Server, enter the hostname or IP address of the
server you wish to connect the simulated aircraft to. At the time of this writing, the only server that will work is
"sweatbox.vatsim.net". Enter your VATSIM CID and password for the other two items. All aircraft that are generated
by TWRTrainer will connect to the VATSIM sweatbox server using your CID and password. (For this reason, multiple connections from
a single CID to sweatbox.vatsim.net are permitted.)
Before you can generate any aircraft, you must first load an airport file. You can only load one airport file per TWRTrainer
session. If you need to switch to a different airport, you must close and restart TWRTrainer.
When you first start TWRTrainer, the "Load Airport File" window will automatically be shown. Select the airport file
from the list. TWRTrainer will then load the airport file, including all the taxiways and runways it defines. See below for
instructions on creating airport files.
After opening an airport file, you'll need to open at least one aircraft file. An aircraft file contains one or more aircraft
which will be created and connected to the specified server. The "Select Aircraft File" will automatically be shown
after you open an airport file when you first start TWRTrainer.
If the aircraft file is successfully loaded, the aircraft will be connected to VATSIM, and information about each aircraft
will be shown in the TWRTrainer window, as shown in the screenshot above. TWRTrainer will automatically pause itself any time
you load an aircraft file. No aircraft will move while TWRTrainer is paused. Click the Unpause menu item to resume the simulation.
See below for details on creating aircraft files.
TWRTrainer provides a comprehensive list of commands which you can use to tell the simulated aircraft what to do. All commands
are sent to the aircraft via radio text messages on a normal radio frequency. By default, this frequency is 199.997. You can
change the frequency that TWRTrainer listens on via the Settings menu. It's a good idea to use a frequency that your student
will not be listening in on so that he/she cannot see what you are telling the aircraft to do.
To issue a command to an aircraft, set your transmit frequency in ASRC/VRC to the same frequency you have TWRTrainer configured
to listen on. Then, radio-select the aircraft you want to control, and type the command (without a leading dot) in the ASRC/VRC
command line, and press enter. The command will go out on the text frequency just like any text instruction you would send to actual
VATSIM pilots while controlling. If the command is recognized and has no errors, the aircraft will not respond ... it will
simply begin to execute the command. The TWRTrainer window may also show confirmation that the command has been received. If the
command is not recognized, or you made a syntax error in the command, the aircraft will respond with an error message.
See the Command Reference for a detailed list of all commands and their syntax.
When you first load an aircraft file, the scenario will start out paused. The aircraft will show up, but they will not be moving. To
unpause the scenario, issue the un command to any one of the aircraft, or click "Unpause" in the menu bar. Note that
any time you subsequently load an aircraft file, the scenario will be paused, even if you are only adding new aircraft to a scenario
already in progress.
To pause an active scenario, issue the p command to any one of the aircraft, or click "Pause" in the menu bar.
To give you a better idea of how a typical TWRTrainer session works, I'll describe a small fictional scenario from my own usage of TWRTrainer
at Boston Logan airport. (KBOS)
First, I start up VRC and connect to the sweatbox server to meet up with the student and make sure nobody else is doing any training on the
sweatbox server in the KBOS area. Then I'll discuss with the student exactly what types of traffic we're going to work on in this session, whether
it be streams of IFR arrivals, mixed heavy/large/small departure flows, VFR traffic in the pattern, a mix of these, etc. Based on that, I'll know
which aircraft file(s) to load.
Next, I'll set up my comms panel in VRC. I'll start up a voice connection to the voice channel we use for training. Then I'll activate the comms
panel entry which contains the TWRTrainer control frequency.
Next, I'll start up TWRTrainer. TWRTrainer then prompts me for the airport file to load, so I choose my KBOS file. Then I'm prompted for an
initial aircraft file. Usually I'll select a file I created called "KBOS_mixed_departures.air". This file contains a wide variety
of aircraft parked all around KBOS, including some at the airline gates, some on the cargo ramp, some light aircraft on the General Aviation ramp,
as well as one or two helicopters. This file gives me a good starting point for just about any kind of TWRTrainer session. If I don't need some of
the aircraft, I can either just let them sit on the ramp, or I can delete them.
Next, I'll usually set up one or more streams of arrival aircraft using the add command. (Remember that you must
have one of the existing aircraft radio selected before you issue a command, even a command which is not specific to any single aircraft, such as the
add command. In other words, TWRTrainer will ignore text sent on the control frequency if it is not directed to
a selected aircraft. This is to allow more than one instance of TWRTrainer to be running at one time, using the same frequency, with two different
instructors controlling each one.)
One form of the
add command allows you to create an aircraft already established on approach to a specified runway, automatically
at the appropriate glideslope altitude for the specified distance from the threshold. So, usually I'll issue several of these add
commands for the same runway, each one spaced 3 to 5 miles apart, the closest one just outside the range of the Tower airspace. This sets up a nice
"string of pearls" for the student to deal with as soon as the session begins.
Once the student is ready to begin, I'll unpause TWRTrainer and begin making the pilot calls. I'll usually start by having one of the aircraft on the ramp
call for taxi, assuming the student will be handling GND duties as well. If not, I'll just taxi them to the active and then report when they're holding short.
If the student is going to be handling IFR clearances as well, then I'll start by having those aircraft call for clearance first. Obviously, it depends on what
position you are actually training the student for ... TWRTrainer works equally well for training the DEL, GND or TWR positions.
When the student responds and gives the aircraft taxi instructions, I will issue the taxi command. A typical taxi command
for KBOS is taxi k n 22r. This tells the aircraft to taxi to runway 22R via the Kilo and November taxiways. Once issued this
instruction, the aircraft will taxi from its present position directly to the closest waypoint (as defined in the airport file) on the Kilo taxiway, then taxi from
there to the intersection of Kilo and November, then from there to the hold short point just before the intersection of November and runway 22R. If TWRTrainer cannot find the intersection of any
two taxiways/runways in your taxi instruction, it will transmit an error message on the control frequency (199.997 by default) so that you can issue a corrected
taxi command. If the taxi route is okay, the aircraft will just start moving.
Here's another common taxi command for KBOS: taxi k c d 27 hs 33l. This command tells the aircraft to taxi to runway 27
via taxiways Kilo, Charlie and Delta, and to hold short of runway 33L on the way there. (The Delta taxiway crosses runway 33L, which is often active for arrivals
when 27 is active for departures.) Once the aircraft reaches the intersection of Delta and 33L, it will hold position and report on the command frequency that
it is holding short of 33L. It will then wait there until you issue either the res (resume) command, or the
cross 33l command. It will then cross 33L on Delta, and continue down Delta until it reaches runway 27, at which point it will
hold short, unless told to position and hold or take off.
Once a departure is holding short of its departure runway, I'll either issue the cto command to clear it for takeoff, or
one of the ctomlt or ctomrt commands to clear it for takeoff and into the left or
right traffic pattern respectively. If required, I'll give the aircraft a specific departure heading to fly on wheels-up with a command such as
cto 140, which will make the aircraft takeoff and fly heading 140 on departure.
After an aircraft is cleared for takeoff, it will either fly the runway heading or the assigned departure heading, and climb until it reaches the initial
climb value specified in the airport file. Normally, the student will have instructed the departure to contact the departure controller (even though there really
isn't one) by the time the aircraft reaches the initial climb altitude. Once the student does so, I'll usually delete the aircraft. It is important that you
don't forget about departures and let them just fly along forever. Since the sweatbox is a shared server, those aircraft may very well stumble into a training
session being conducted at another field.
For aircraft remaining in the pattern, there isn't much you need to do other than make sure the student gives the appropriate traffic pointouts and touch-and-go
clearances in a timely manner. However, there are several commands available that allow you to take control over the aircraft in the pattern. These commands allow
you to do such things as making the aircraft fly a 360 degree turn for spacing, extend certain legs of the pattern, fly different types of landings (touch-and-go,
stop and go, low approach, full stop), etc. See the Command Reference for details.
In addition to having aircraft on the ground call up for taxi and takeoff instructions, I'll also have some of the aircraft established on final check in. When the student clears the
arrival to land, there is nothing more you need to do to get the aircraft to actually land, assuming it was added using the add
command format which specifies a runway. (See the Command Reference for details.) When you do so, the aircraft
are already intending to land on the specified runway. If the arrival was loaded a different way, such as from an aircraft file, then it will need to be told to
enter the pattern before it will actually perform a landing.
After the arrivals land, they will slow down until reaching about 45 knots, at which point they will exit the runway via the next available taxiway. The direction
they choose to exit the runway (right or left) depends on the runway definition in the airport file. (See below.) Once the aircraft has exited the runway, it will
report clear on the control frequency. At that point, I'll usually wait for the student to notice that the aircraft is clear, at which point the student should
tell the aircraft to contact GND, or give it taxi instructions to the gate.
Note that when you issue a taxi instruction that ends in a parking space, the aircraft will automatically delete itself when it reaches the parking space. This is
default behavior that can be disabled via the "Settings" menu. Here's an example taxi command that brings the aircraft to a parking space:
taxi f a @b3 hs 4l. This is a typical taxi command given at KBOS to an arrival that just landed on runway 4R and exited on
taxiway Hotel. When given this command, the aircraft will taxi from its present position on Hotel to the intersection of Hotel and Foxtrot, then follow Foxtrot
to the intersection of Foxtrot and Alpha, holding short of 4L along the way. After it is told to cross 4L, it will continue up on Foxtrot, turn onto Alpha, then
follow Alpha to the waypoint on Alpha which is closest to parking space B3, at which point it will turn off of Alpha and taxi directly to parking space B3, then delete itself.
Depending on the skill level of the student, I may also throw in some VFR pattern aircraft, helicopter arrivals and departures, VFR departures, etc. Perhaps also
some go-arounds, non-responsive pilots or pilots that don't follow instructions quite right, etc. One favorite training tactic is to not readback hold
short instructions, and have the pilot blunder across an active runway even if he was told to hold short of that runway. This helps ensure that the student listens
for the pilot to read back the hold short instructions, and repeat them if needed.
Oviously, throughout the session I'll also add additional departures (at the gates or parking ramps) and arrivals, using the add
command. You need to use your best judgement to determine how often to add new aircraft during the session. A good rule of thumb is that if there is dead time on
the radio frequency, it may be time to add some aircraft. If the student is "caught up" with the scenario and has nothing to do but watch the blips fly
around, then he's not learning much. At ZBW, we've found that students progress quickest when they're kept at or just beyond the edge of their capabilities as much
During the session, I'll periodically issue the ops command. This command shows you how long the session has been running (not
including paused time), the number of arrivals and departures the student has handled, and the number of operations per minute. These stats can be useful for setting
standards for certification testing or gauging the student's progress over time.
An airport file consists of a few lines of general information about the airport, followed by multiple sections that define
taxiways, runways, hold points, and parking spaces. Note that airport filenames must end in .apt.
The Airport File Header
The first portion of an airport file contains general information about the airport. This group of lines is called the Airport
File Header. Here's an example of the header for KBOS:
initial climb props=3000
initial climb jets=5000
The first line, icao, specifies the ICAO code for the airport. The magnetic variation line is self-explanatory. This value must
be correct for aircraft to be able to fly headings correctly. The field elevation is self-explanatory, and must be correct for
aircraft to fly approaches and land correctly. It is specified in feet. Pattern elevation is also given in feet. Pattern size
is specified in nautical miles, and determines how long the crosswind and base legs of the traffic pattern will be, by default.
The initial climb values specify at what altitude departing aircraft will level off if not given further climb instructions.
The "jet airlines" and "turboprop airlines" settings determine the callsign prefix used when generating
aircraft with the "add" command. See the Command Reference for
details. The "registration" setting determines the callsign prefix used when generating VFR aircraft.
Parking Space Sections
Using parking space sections, you can define points on the airport surface to which you can direct aircraft to taxi and stop. You
would normally define one of these for each major gate or ramp parking spot. Here are a few examples from the KBTV file:
The above example shows four gate parking spaces, plus three General Aviation parking spaces. Note that the parking space
can be named anything you want (using letters and numbers, no spaces, dashes or punctuation) ... the ones shown here are
just examples. For example, in the KBOS file, we use "CARGO1" to define a parking space on the cargo ramp.
Each runway section defines a single runway (both directions) for the airport. Here's an example from the KBTV file:
This defines the 33/15 runway, with a displaced threshold for runway 33 of 500 feet, and no displaced threshold
for runway 15. It defines the default exit turn direction for runway 33 as left. This means that for the reciprocal
direction (runway 15), aircraft will by default exit to the right. You can override the turnoff direction using
commands. See the Command Reference for details. Note that the displaced
threshold and turnoff entries are optional for each runway.
Note: Do not use a leading zero when specifying runways. In other words, "[RUNWAY 22/4]" is valid, while
"[RUNWAY 22/04]" is not.
The remainder of the RUNWAY section defines the coordinates that make up the runway. You need to specify one coordinate
for the start of the runway, one for the end, and one for each intersection along the runway. These waypoints must be
in order for the aircraft to follow the runway properly. In the example above, there are 8 points defined for the runway.
The first one is the start of runway 33. The next 6 are intersections along the runway. These include intersection points
with taxiways or other runways. The last point is the end of runway 33, which also serves as the beginning of runway 15.
See below for details on defining intersection points.
Taxiway sections are almost identical to runway sections. They obviously do not have displaced threshold or turnoff entries,
though. Here's an example from the KBTV file:
This section defines the coordinates for taxiway Foxtrot. As with runway sections, these coordinates must be in order for
the aircraft to follow the taxiway correctly. See below for details on defining the intersection points along the taxiway.
Hold Point Sections
A hold point section defines a special location on a taxiway where aircraft must often hold position awaiting further taxi
instructions. A good example is the "Bravo Hold Point" at KBOS. This is a point on the Bravo taxiway just prior to the
runway 9 jet blast area where aircraft must hold position until the Ground or Tower controller tells them to continue taxi. Here's
how you define a hold point:
This creates a hold point called "BHP". Note that you can name the hold point anything you want, using letters and numbers.
You cannot use spaces.
Also note that aircraft will not automatically hold at defined hold points. You must tell them to do so by including the name
of the hold point in your taxi command hold short list. See the Command Reference for
details on forming the taxi commands. Here's an example:
taxi k b 4r hs bhp
This taxi command will instruct the aircraft to taxi to runway 4R via Kilo and Bravo, and hold short of the BHP.
How Intersection Points Work
When you command an aircraft to taxi from one taxiway to another, or along a runway, it does so by examining the intersection
points defined in the airport file. (See above.) When attempting to taxi from one taxiway or runway to another, the aircraft will look
for the one intersection point that the two taxiways/runways have in common. It will then taxi along the current taxiway/runway
until reaching that point, then turn onto the intersecting runway/taxiway. These intersection points don't have to match exactly ...
they must only be within about 100 feet of each other. If the aircraft cannot find such an intersection, it will send you an error
saying that the two taxiways/runways do not intersect. If that happens, you'll need to redefine your airport file with better precision.
An aircraft file (also called a scenario file) consists of one or more aircraft definitions. An aircraft definition is a single line
containing the basic starting information for a single aircraft in the training scenario, such as location, heading, speed and altitude.
Following is a description of what data goes in each colon-delimited field:
Callsign:Type:Engine:Rules:Dep Field:Arr Field:Crz Alt:Route:Remarks:Sqk Code:Sqk Mode:Lat:Lon:Alt:Speed:Heading
Type is the aircraft ICAO type code such as B738. Engine is either P for Prop, T for Turboprop, J for Jet, or H for Helicopter. Rules is
either I for IFR or V for VFR. Cruise alt and current alt are specified in feet. Lat and Lon are specified in decimal degrees. Squawk mode
is either N for normal or S for standby.
Here is an example aircraft file:
AAL123:B190/A:T:V:KBTV:KMHT:15500:BTV MPV LEB MHT:/V/VFR/CHARTS:1200:S:44.46370:-73.15221:335:0:360
This example file contains two aircraft, AAL123 and DAL211. AAL123 is parked on the ground, and DAL211 is in flight. When creating
aircraft which are to start parked on the ground, make sure their current altitude matches the field elevation specified in the airport
file, and make sure their speed is zero.
You can either create aircraft files by hand, or you can create aircraft within a TWRTrainer session using the "add" command,
then save all current aircraft as an aircraft file. You do this by selecting "Generate Aircraft File" from the File menu. TWRTrainer
will generate the aircraft file and copy it to your clipboard. You can then paste the lines into a text file and save it. Note that this only
includes the position of each aircraft, and not their last instruction, so it cannot be used as a way to save a scenario to be resumed later.
Note that aircraft file filenames must end in .air.
The best place to get support for TWRTrainer is via the Sweatbox forum on VATSIM.
Also, feel free to
(Ross Carlson) with comments or suggestions.