ATC-pie

From FlightGear wiki
Revision as of 12:47, 23 July 2015 by Mickybadia (talk | contribs) (Added tip on customising radar colour)
Jump to navigation Jump to search
ATC-pie
ATC-pie logo
ATC-pie at the KSFO mess
ATC-pie at the KSFO mess
Developed by Michael Filhol
Initial release February 1, 2015
Latest release July 19, 2015 (r5)
Written in Python3
OS Any
Platform Qt5
Development status Active
Type ATC client
License GNU GPL v3
Website

ATC-pie is an air traffic control simulation program featuring solo training and a multi-player game mode to connect to FlightGear networks. It is essentially designed for realism, and simulates many features of real-life ATC tasks such as transponder identification, strip rack and sequence management, handovers to/from neighbouring controllers, ATIS recording, flight plan editing, routing and conflict solving.

ATC-pie is free and open source, programmed in Python3 for Qt5 hence system-independant, only both must be installed as well as the python3-qt5 bindings. That done, it is meant to work straight away, with no other resource to install or make/compile command to run. No need to install or update FlightGear, download scenery or fetch any external resource before it can run.

Program features

The features listed below have been tested on various Linux versions and Windows. We are still waiting for Mac users to report.

Game and environment

World data:

  • Real world METAR updates from selectable weather station
  • Real world declination lookup and true/magnetic distinction
  • Airport and navigation data retrieved from the latest X-Plane file set
  • Custom additions possible in separate files

Multi-player and network environment:

  • Multi-player game mode with configurable FGMS connection
  • ATC handovers: strip exchange with OpenRadar and other ATC-pie instances in range
  • Interface with Lenny64's flight plan data base, including in-game FPL retrieval, filing and editing
  • In-app session announcement facility to post on Lenny64's popular ATC event page
  • Ignore contacts

Solo game mode:

  • Free combination choice of APP, TWR and DEP control positions for custom training
  • Handovers to/from virtual ATCs
  • Instruction interface and pilot read back
  • Adjustable difficulty (traffic density)
  • Departure–arrival and ILS–visual balance options
  • Configurable runways in use, entry and exit points

GUI:

  • Floatable, dockable and closable GUI panes: strips, radios, text chat, etc. (window layout saved)
  • Notification system combining selectable sounds, status bar messages and a time-tagged history
  • General and airport-specific settings saved on close and restored on restart
  • Customisable colours
  • Personal notepads saved across sessions

Radar and contact

Transponder contact:

  • Mode-dependant behaviour (off, A, C, S) and choice of simulated mode for non-equipped aircraft models
  • Radar identification assistant (unique squawk link between radar pick-up and strip assignment detection)
  • Individual and general cheat modes to override XPDR settings or reveal those turned off

Radar scope:

  • Custom radar background drawing and image display (e.g. to display real procedure charts)
  • Variety of show/hide options for navigation points, vectors and route assignments, etc.
  • Point-to-point heading & distance quick measuring tool
  • Custom text labels to annotate radar background

ATC management

Strips, racks, flight plans:

  • Strip drag&drop along and across user-defined racks, with configurable colours
  • Strip drop on neighbouring ATCs to hand over
  • Link strips to flight plans and radar contacts to merge editable details and inform radar display
  • Conflicts between linked elements reported
  • Work with local FPL copies and manage sync with online publication

Routes, vectors, conflicts:

  • Route parsing and drawing
  • Current leg and next waypoint display with geodesic calculations of headings and distances
  • Assign vectors and change routes with direct mouse gestures
  • Anticipated route conflict warning and separation incident alarm
  • Visible mismatches between assigned vectors and picked up positions

Communications

Radio:

  • FGCom integration, incl. echo test and possible use of externally running client
  • ATIS recording with information letter and pre-filled preparation notepad
  • Multiple and single frequency transmissions
  • Frequency-specific sound level selection

Text chat:

  • Custom preset message list and automatic line completion
  • Preset and custom text aliases for context-sensitive replacements
  • Message history and single-click message recall
  • Hardcore communication sim possible by disabling unknown senders' callsigns

Screenshots

Playing solo mode with three coloured racks  
Radar identification marked in blue  
Depiction of airport tarmac and objects  
Background image display  
Hand drawing for LSGG procedures  
All-in-one display of assignments  
Horizontal separation rings  
Route conflict warning  
Strip detail sheet with editable route  
ATIS recording feature with scrap notebook  

Working principles

General

You are the air traffic controller, and players will connect to the network (or AI traffic be simulated in solo mode) with different types of aircraft and transponder equipment. As in real-life, the radar is SSR, hence will show you only (unless you cheat) what you pick up from on-board transponders in your range. That means:

  • If a transponder is off or on standby, you will not see the aircraft on your radar screen.
  • If a transponder is on, you will at least be able to see its position and read the transponder code, possibly its altitude and even its type and callsign, depending on the mode set by the pilot.

Strips

Your basic traffic flow and sequence working unit is the strip, each representing a controlled (or soon expected) aircraft. Strips are created, filled with details and moved along and across racks until handed over to a different controller or discarded. Strip details include:

  • most importantly, the aircraft's callsign, to be used on the radio;
  • information like aircraft type, airspeed, route... that can be specified by the pilots themselves when filing flight plans;
  • transponder code and flight parameter assignments (or vectors: heading, altitude/FL, speed).

Linking strips

Strip details can be manually edited, but every strip can also be linked to a flight plan and/or a visible radar contact on the scope screen—a strip can only be linked to one flight plan and one radar contact. Linking to a strip will automatically:

  • make the strip display the missing elements made available by the linked aircraft transponder or flight plan;
  • label the radar contact dot with the more informed linked details, e.g. assigned altitude.

Any detail mismatch between a strip and its linked flight plan or radar contact will be reported for you to resolve.

Radar identification

To identify an aircraft and link the right radar contact to a strip, an ATC can rely on different things. He can read an aircraft's callsign straight away if its transponder has mode S turned on, tell from reported positions and altitudes, or use a transponder code. For instance, say a VFR traffic makes an initial radio contact giving his callsign and approximate position. ATC will typically pull out a new blank strip and give the pilot a unique transponder code to squawk, writing it on the strip alongside the announced callsign, then wait for it to appear on the radar. This allows for radar identification of aircraft–strip pairs such that:

  • the strip is assigned a transponder code;
  • no other strip is assigned the same code;
  • the aircraft is the only one squawking that code in radar range.

ATC-pie identifies such pairs automatically and reports them to you so you can properly link the two and get back to the pilot: "radar identified".

User guide

This section helps one download and run ATC-pie, and lists a few tips on some of its features. Other sources to learn to use the program are:

  • the online video tutorial on YouTube (follow/bookmark the link to the full playlist);
  • the in-app quick reference available from the Help menu (summary of mouse/keyboard gestures, display conventions, etc.).

Anyone motivated to write a full user guide is obviously welcome to contact the developer.

Getting it to run

Downloading

There are essentially two ways of downloading ATC-pie: one is to download a tarball to extract locally; the other is to clone the Git repository. The latter requires Git, but will keep you in sync with updates more easily. Your choice. In either case, you will have no compiling to do (make, etc.), but do make sure you have the few dependencies installed (e.g. Qt5), listed in the README file.

Downloading the tarball:

  1. get the latest stable version from the project page;
  2. extract the files to the directory of your choice.

To clone the repository:

git clone git://git.code.sf.net/p/atc-pie/code ATC-pie

When a new release is announced and if you have cloned the repository, you can update your software with a single command from the downloaded directory:

git pull

Starting the program

Depending on your system and preference, you might be double-clicking, typing stuff or pulling your hair out. In any case what you need to start the program is to run a Python3 interpreter on the ATC-pie.py file in the top-level directory. To start at a chosen airport location, say with code ICAO, add a system command-line argument, which may look as simple as:

./ATC-pie.py ICAO

If no ICAO code is given, good old KSFO will be chosen as default. After a few seconds, you should see the main window appear with a radar scope and a depiction of your airport in the centre.

Additional command-line options are available:

  • --mp-callsign=callsign to set a network callsign directly, modifiable on MP connect (default: ICAOobs)
FGMS callsigns for ATCs typically start with the ICAO code of the controlled airport or sector, and end with a hint on the provided service: twr, gnd... When choosing your callsign on MP connect, make sure it is unique, and note that FGMS restricts callsign length to 7 characters. :-(
  • --fgcom-server=server-address to change the server used by internal FGCom radio boxes (default: fgcom.flightgear.org)
  • --fgcom-ports=port-spec to specify the local ports FGCom should use for internal FGCom radio boxes
Specify a comma-separated port number list. The first one becomes reserved for echo test and ATIS recording while every other port will allow for an additional radio box in the game. Alternatively, enter a string of the form reserved+nboxes as a shortcut for a contiguous range of ports (default: 16665+4, i.e. 16665 for the reserved port, plus 16666 through 16669 for up to 4 radio boxes).

If running ATC-pie for the first time and intending to use the radio, check the FGCom version setting (System menu). Try an echo test and read the resources/fgcom/Notice file.

Feature notes

This section describes a few major features. See more exhaustive list at the top of this article.

Background drawings

Background drawings allow to decorate radar scopes with all sorts of maps and useful information about the airspace, terrain or procedures.

There are two ways of drawing in the radar background. One is to import image files with transparency, the other is to write a text drawing specification file to draw coloured lines and label points. This allows to import anything from the most complex coloured height map to the the most schematic airspace outline. All images are positioned and drawings points specified using lat/lon coordinates or navpoints in radar range. The resources/bgdrawings/Notice file explains how to import and create background drawings.

For example, you can map out SID/STAR routes with one image per published chart, named by procedure and associated runways to make in-game selection easy. If you want more than schematic line plots of the procedures, the best way is certainly to draw the images yourself with good enough resolution, e.g. with Gimp. Superimpose a drawing layer on top of a real map canvas, or over a screenshot of your ATC-pie radar with pinned navaids as landmarks. If you have proper to-scale documentation, it is worth trying the command below (requires ImageMagick) to turn the white background of a ready published chart into transparency, and checking if the rendered images are acceptable and zoom-resistant enough.

convert -transparent white input-file.png output-file.png

Use the image positioning helper tool in the System menu if you want to adjust image corners visually rather than programmatically. All visible pixmap drawings will be moved simultaneously, so you can work with several at a time if you need to. On dialog box close, a file is generated in the output folder for you to open and copy/edit, or use as a direct substitution.

Multi-player strip exchange (handovers) and OpenRadar interoperability

The handover feature in ATC-pie is based on OpenRadar's exchange server to enable ATC coordination between users of both software programs. However, it is to note that their philosophies differ in several ways:

  • OpenRadar's basic processing unit is the FGMS callsign, whereas ATC-pie's is the strip;
  • OpenRadar's concept of handover is based on a shared notion of aircraft ownership, whereas ATC-pie allows any controller to pull out a strip, write any callsign and link it to a radar contact;
  • in the OpenRadar philosophy, a handover must be acknowledged by the receiver for the sender to lose ownership and for all neighbouring OpenRadar users to see the handover complete, whereas ATC-pie considers that a strip sent through the hand-over pipe is gone and should land directly on a receiver's rack at the other end, without anybody else necessarily to know.

For most interactions to work while still respecting both philosophies as much as possible, the following principles were chosen:

  • ATC-pie users can only hand over strips that are linked to a radar contact (no lone strip can be sent);
  • aircraft under ATC-pie control are not shown as "owned" to OpenRadar users;
  • handovers from ATC-pie will fail if an OpenRadar user in range is claiming ownership;
  • when sending to ATC-pie controllers, OpenRadar users will see their transfers acknowledged straight away, unconditionally.

Callsign exchange policy:

  • O-R to ATC-pie: FGMS callsign will appear on the strip, as if the sender had filled the detail properly;
  • ATC-pie to O-R: callsign resolved for the receiver, sender's entry will reappear next time ATC-pie handles the strip;
  • pie-to-pie handovers: strip detail preserved, whether present or absent.

In practice, in ATC-pie, a strip can be handed over by dropping it on the chosen ATC in the list of connected controllers in range. Received strips appear unlinked on the reserved rack, with an identification of the sender which disappears as soon as the strip is clicked on.

Routing and conflict warnings

ATC-pie analyses routes and assigned vectors to assist traffic management and anticipate path conflicts between controlled aircraft.

A route is parsed for every strip with valid departure and arrival airports, as follows:

  • tokens in the route field are whitespace-separated;
  • each recognised navpoint token (world navigation aid, airfield, fix, RNAV point) creates a waypoint on the way to destination, and a route leg from the previous waypoint;
  • other tokens are kept as route leg specification to the following waypoint;
  • if ambiguous, a waypoint is always the nearest homonym to the previous, i.e. to the point beginning the leg.

When a route is parsed correctly, "OK" shows near the route field on the strip detail sheet, and if a radar contact is linked:

  • the strip shows only the remainder of the route for this contact, based on distance to destination;
  • the route to go is drawn as a dotted line on the radar scope when the contact is selected (unless turned off);
  • the current route leg is displayed in the selection info pane with its specification string if any;
  • the info box contains the current waypoint and geodesic heading to reach it.

If no route can be interpreted (missing or invalid DEP or ARR), "!!" is displayed on the detail sheet and linked info boxes will show the strip destination detail (ARR) if it is filled.

ATC-pie also features a conflict warning system, which can be activated or turned off from the Options menu. It uses route and vector assignments to anticipate path conflicts and alert you to take action and prevent separation losses.

When looking for conflicts, a horizontal (ground projection) path is considered for every aircraft with a linked strip and a parsed route or an assigned heading vector. An aircraft is assumed to follow its route, unless a heading vector is given in which case it is assumed to be flying the assigned straight course. Path conflicts occur when horizontal paths intersect and the intervals between respective current and assigned altitudes overlap. When no altitude is assigned, the interval is one around the current altitude. When an aircraft's altitude is unknown, any assigned altitude will be considered instead.

Another (more serious!) possible alarm is the separation incident, which calls for immediate action. The table below summarises the different levels of conflicts, ranked in decreasing order of emergency.

Conflict warnings in ATC-pie
Alarm Shown on scope (default colours) Meaning
Separation incident Bright red intersecting circles Separation loss between aircraft, a serious ATC mistake!
Path conflict Red circles and paths Anticipated paths and altitudes are intersecting
Possible path conflict Yellow circles, red paths Ground projection of paths are conflicting but not all altitudes are known

Solo training mode

This mode allows to train on your own in different situations. Three combinable positions are available:

  • tower (TWR), controlling runways and immediate surroundings;
  • departure (DEP), bringing departing traffic to their exit point;
  • approach (APP), vectoring arrivals onto final.

In any case, you will be controlling virtual IFR planes via the software interface, and receiving and handing over strips to virtual ATCs, depending on your position and on the aircraft's intentions (see table below). Approaches can be requested ILS or visual, and the balance between the two is adjustable from the solo mode settings.

Assuming APP, aircraft requesting ILS must be vectored to intercept a runway localiser and cleared for ILS approach, whereas those requesting visual require vectors until they report the expected runway is in sight. Then, approaching aircraft must be handed over to TWR, unless you are in the TWR position as well. If you are, you must clear them to land—or they will climb back up for go-around—and hand them over to ground control (GND) once they have vacated the runway. Tower also manages departures, which appear ready holding short of runways. After take-off, hand over your strips to departure control, unless assuming DEP yourself. When doing DEP, you must hand outbound aircraft over to the en-route centre (CTR) once they are high enough and close enough to their exit point if specified.

Handovers with virtual ATCs
Departure strips Arrival strips
Assuming positions Receive from Hand over to Receive from Hand over to
DEP only TWR CTR N/A
APP only N/A CTR TWR
TWR only GND DEP APP GND
APP+DEP TWR CTR CTR TWR
TWR+DEP GND CTR APP GND
TWR+APP GND DEP CTR GND
TWR+APP+DEP GND CTR CTR GND

Vectors are given by means of the vectoring assignment tool (click&drag on radar contact for heading, with SHIFT for altitude/FL and speed). Other instructions (line up and wait, clear to land, etc.) can be sent from the instruction dock. Pull it up from the View menu if it is not visible. Non-vectoring instructions are sent to the callsign entered in the top field, which should fill automatically on aircraft or strip selection if a callsign is known.

Things you can train for:

  • approach in dense traffic: select APP position only and increase traffic density;
  • towering a single runway, optimising its use: select TWR position and an equal balance of departures and arrivals;
  • change of runways (e.g. irl after wind direction change): start with APP+TWR and select a runway for arrivals at least, play for a while and go back to the dialog to change for the opposite runway;
  • etc.

Tips

Here are a few tips to help you navigate and use the program.

Interface and information display

The Options menu is divided in three sections, respectively:

  • session options: go back to their default setting on restart, e.g. rack sync option;
  • airport-specific settings: saved and restored when restarted at same airport, e.g. runway ILS capability;
  • global settings: saved and restored regardless of airport, e.g. preset text chat messages.

You can customise the radar colours by editing the colour codes in the settings/colours.ini file generated on first run.

Heading displays are mostly magnetic so they can be read out to pilots. The only exceptions perhaps are the navigator and handover list tooltips, for easier human identification on the scope. All directions are geodesic.

The transition level displayed in the weather analysis is the lowest flight level that is still above the transition altitude. This does not mean the lowest to be expected in ATC clearances, which may be higher, for more vertical separation on either side of the transition layer or due to coordination with neighbouring zones and fields.

The grouped tick marks along the localiser line (when shown) indicate best altitudes AMSL for final approach along the defined flight path angle: every mark in a group is 1,000 ft.

Radio and communications

Say you are TWR coordinating with GND at your airport, and you want to monitor both radio frequencies while you are only in charge of one. To set this up, start your radio box on TWR frequency and turn on a second one to monitor GND, tick "Kbd PTT" only for TWR so that you only transmit to your frequency and don't interfere with the other, and set the volume to "soft" on the latter so that you can always tell if a message is for you to answer or not.

The PTT turns off sounds option is recommended for those of you who do not wear headsets, as it will avoid GUI sound notifications being picked up by your microphone while transmitting on frequencies.

For more efficient text chat, text aliases ($wind, $qnh, $icao...) are available for both instant and preset chat messages. They automatically expand to the current value when the containing message is sent. Also, custom aliases can be assigned to linked contacts directly in the strips' comments for more productivity with preset messages. Have a look at the quick reference available from the Help menu, Text aliases section.

Everything up to the first pipe character (|) if any in a text chat line will be stripped before the message is processed and sent. For quicker access to preset messages if you use them and the keyboard a lot, you can therefore prefix your messages with a custom shortcut and a pipe, which will enable autocompletion to pull up the desired message line as you start typing the prefix. Here is a preset message example enabling something like a dot-command for sending a bearing to your airport to the currently selected pilot:

.qdm|Heading to airport $qdm

Strip and flight plan details

Every initial contact by a pilot should basically make you hit F2 and enter at least the call sign announced. You should then soon figure out if:

  • a flight plan is filed, in which case you can save the strip relatively quickly and look for the FPL to link to it (middle click on the FPL entry);
  • a flight plan must be filed (e.g. IFR departure not filed by lazy pilot), which only takes a tick in the bottom-line box before saving to open a freshly linked FPL detail sheet to fill;
  • he was asked to contact you by a previous ATC, in which case you may have a strip handed over to you already (check the unassigned strip rack);
  • etc.

In airport input fields, typing a single dot will instantly fill the box with your ICAO position. Use this as a shortcut from/to your airport when filling details.

Resolving strip–FPL conflicts:

  • to confirm strip details: open the strip detail sheet, tick the "push details to FPL" box and save to propagate the strip details;
  • to confirm FPL details: "pull FPL details" from the button menu to reset the conflicting strip details to the values filled in the linked flight plan;
  • to confirm some details of each source: open the strip sheet, get rid of the bad details before pushing to the flight plan.

Resolving local–online flight plan conflicts:

  • to update the online version with your local modifications, double-click the flight plan and tick the "publish" box before saving (if still decorated red, there was a network problem or the change was rejected by the server);
  • to discard all local modifications of an online FPL, remove the FPL from the list and check for new flight plans again (the deleted entry should be retrieved with online state).

FAQ

Questions frequently asked (at least twice) about the program:

Q: How do I start anywhere else than bl*ody KSFO?

A: Use a command-line argument: ./ATC-pie.py ICAO

Q: Why am I not seeing this aircraft on my radar? I know it is there: the pilot is sending chat messages and/or it is visible on the live tracker map...

A: You only see an aircraft if its transponder is turned on, i.e. responding to your radar ping. You should tell the pilot to turn his transponder on. If the transponder feature is not supported by the aircraft model, it will be simulated by ATC-pie according to the fallback mode you have selected in the settings dialog, hence will be visible for any non-zero (0=off) selection. The other radical way to go is to cheat to see him, with menu options "reveal OFF/STBY" or "radar cheat mode".

Q: What is the strip exchange server? Which one to use?

A: The strip exchange feature allows you to hand over strips to ATCs who are connected to the same server and within 180 NM from your position. The public server currently open for general multi-player use is http://h2281805.stratoserver.net/FgFpServer. To hand over a strip, drag it from its rack and drop it on the chosen callsign in the ATC handover list. Publicise your frequency so that ATCs around know what to tell pilots for them to contact you!

Q: What nickname should I use for the strip exchange server? Where to get my ID?

A: This feature is not linked to any account or identification process; just choose any name you would like to be recognised by. It will appear in a tooltip over your callsign in the handover list of ATCs who will connect near enough to see you. In a sense, this feature is more social than technical, but makes sense as typical ATC callsigns remain mostly anonymous over MP. Use this field so that other players can identify you.

Q: Can I draw SID and STAR procedure routes on the radar?

A: Yes, and virtually anything else, using background images and hand drawings. See corresponding section above.

Q: How can I add such drawing?

A: Read the resources/bgdrawings/Notice file to learn how to add drawings to your airport sessions and position them on the radar screen. Also have a look at the packaged KSFO example.

Q: FGCom radio is not working. What is going on?

A: There can be a variety of reasons, all of them to rule out before reporting a bug in the program. Start a single ATC-pie instance and try the echo test (System menu). If it works, you may skip directly to item 3 below.

  1. Bad FGCom version setting
    Verify the "FGCom version" set in the System menu, which should name a subdirectory in resources/fgcom and suit your operating system (see Notice file). Four versions are initially packaged with ATC-pie: Linux64, Linux32, Mac, Win32. FGCom version should be 3.4 (January 2015).
  2. FGCom server down
    This can happen, unfortunately even for up to a few days. Check for responses from the server, e.g. with ping fgcom.flightgear.org.
  3. FGCom subprocess error
    If the server is up (responding to ping), check for errors in the logged FGCom output files in the output directory.
  4. Port mess-up on your side
    If you are running multiple instances of ATC-pie, make sure you have no more than one radio box on every port. In any case, verify you only choose available ports that are not already in use by your operating system for example. Typically, default ports (from 16661 counting up) work fine, but you will have to change them for parallel instances, using the --fgcom-ports= command-line option (see section: starting the program). To check what port a radio box is using, see its "on/off" button tooltip.