Traffic Generation Utility for VATSIM Controller Training
Current Version: 1.0 - Released: 10/14/2006

Description | Screenshot | Acquiring TWRTrainer | Documentation | To Do List | Revision History |

TWRTrainer is a traffic generator for use with the VATSIM sweatbox training environment. It is intended to be used to generate traffic local to a single airport for the purposes of training controllers for the Tower, Ground and Clearance Delivery positions. Aircraft can be commanded to taxi along specific routes, hold short, position and hold, take off, fly patterns, perform touch and goes, stop and goes, low approaches, depart the area, fly inbound for landing, etc. Aircraft can be added with commands or by loading pre-made scenario files.

Acquiring TWRTrainer

TWRTrainer must be acquired through your local training staff.


Available Documentation

In addition to the documentation included on this page below, the following reference files are available:

Initial Setup

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 "". 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 are permitted.)

Opening an Airport File

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.

Opening an Aircraft File

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.

Controlling Aircraft

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.

Pausing the Scenario

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.

An Example TWRTrainer Session

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 as possible.

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.

Creating Airport Files

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:

	magnetic variation=16
	field elevation=20
	pattern elevation=1020
	pattern size=1
	initial climb props=3000
	initial climb jets=5000
	turboprop airlines=EGF,USA,COA,CJC,JZA

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:

	44.46893 -73.15392
	44.46829 -73.15361
	44.4679 -73.15348
	44.46365 -73.15263
	44.4637 -73.15221
	44.4639 -73.15272
	44.46538 -73.15325

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.

Runway Sections

Each runway section defines a single runway (both directions) for the airport. Here's an example from the KBTV file:

	[RUNWAY 33/15]
	displaced threshold=500/0
	44.46571 -73.14166
	44.46598 -73.14211
	44.47044 -73.14932
	44.47263 -73.15287
	44.47329 -73.15394
	44.47614 -73.15855
	44.47953 -73.16403
	44.48049 -73.16559

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

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:

	44.47371 -73.15058
	44.48098 -73.16257
	44.48108 -73.16299
	44.4811 -73.16485
	44.48049 -73.16558

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:

	42.35523 -71.01747

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.

Creating Aircraft Files

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
	DAL211:B738/F:J:I:KBOS:KBTV:24000:MHT MPV:/V/CHARTS:3401:N:44.41194:-73.05567:6000:230:327

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.

Obtaining Support

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.

To Do List

  • Create a way to save a session to be continued later.
  • Create a way to record and play back sessions.
Revision History

Version 1.0.0 - April 23rd, 2006

  • Initial Public Release

© Copyright 2006 Ross Alan Carlson. All rights reserved.