ATC-pie

From FlightGear wiki
Revision as of 19:25, 20 March 2015 by Mickybadia (Talk | contribs) (Accompanies new release)

Jump to: navigation, search
ATC-pie
ATC-pie logo
ATC-pie at the KSFO mess
ATC-pie at the KSFO mess
Developed by Michael Filhol
Initial release Febuary 1, 2015
Latest release March 21, 2015
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 radar simulation program for the FlightGear multi-player network, initially released Febuary 2015. It is comparable to OpenRadar, but essentially designed for realism. It simulates many features of real-life ATC tasks such as strip rack and sequence management, handovers to/from neighbouring controllers, transponder identification, flight plan filing, ATIS recording.

It is 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

Features listed below have been tested on various Linux versions and Windows. Still waiting for Mac users to report.

Environment

World data:

  • Real world METAR updates with selectable weather station
  • Real world declination lookup and true/magnetic distinction
  • Airport and navigation data retrieved from the latest X-Plane file set

Multi-player environment:

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

GUI:

  • Floatable, dockable and closable GUI panes: strips, radios, text chat, etc. (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
  • Personal notepads saved across sessions

Transponder and radar contact

Transponder support:

  • Mode-dependant behaviour (modes 0, A, C, S)
  • Choice of simulated mode for the many FlightGear aircraft models still not equipped
  • 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:

  • Variety of show/hide options for navigation points, aircraft info boxes, vectoring assignments...
  • Point-to-point heading & distance quick measuring tool
  • Custom radar background drawing and image display
  • Custom text labels to annotate radar background (saved across sessions)
  • Ignore contacts

ATC management

Strips and flight plans:

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

Routes and vectors:

  • Route parsing, current leg and next waypoint display
  • Geodesic calculations of headings and distances
  • Directly assign headings, altitudes/FLs and speeds with click&drag on controlled radar contacts
  • Conflicts between assigned and picked up routes and altitudes reported

Communications

Radio:

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

Text chat:

  • Preset message list management
  • Text aliases for context value replacements
  • Message history recall
  • Hardcore comm simulation possible by disabling unknown senders' callsigns

Screenshots

Radar identification marked in blue  
Fine airport tarmac depiction  
All-in-one display of vectors and conflicts  
Horizontal separation rings  
Strip detail sheet with editable route  
ATIS recording feature with scrap notebook  
Background image display  
Custom line drawing at EKCH  

Working principles

General

You are the air traffic controller, and players will connect to the network 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. Details written on strips include:

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

Linking strips

Double-clicking on a strip will open a strip detail sheet where those details can be manually edited, but each 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 to 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.

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 it is visible (or cheated), 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 is only poor standalone documentation. It helps one download and run ATC-pie, and lists a few tips on some of its features. Yet better sources to learn the program are:

  • the in-app quick reference from the help menu (summary of mouse/keyboard gestures, etc.);
  • the tutorial videos (to be announced).

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 snapshot;
  2. unzip 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 your network callsign directly (default=ICAOobs)
  • --fgcom-ports=comma-separated-port-numbers to specify the local ports FGCom should use, the first one being reserved for echo test and ATIS recording, every other port allowing for an additional radio box (defaults: 16665 for reserved port; 16666 through 16669 for up to 4 radio boxes)

Tips

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

Setup and interface

FGMS callsigns for ATCs typically start with the ICAO code of a controlled airport, 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. :-(

A few facts on information display:

  • 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.
  • 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.

In airport input fields, a single dot will instantly be replaced by your ICAO position. Use this as a shortcut from/to your airport when filling FPL/strip detail sheets.

Any strip with valid departure and arrival airports will contain a parsed route:

  • recognised navpoints in the route field (whitespace-sparated tokens) create waypoints on the way to arrival;
  • other tokens are stored as route leg specifications to the following waypoint;
  • the current route leg of the selected aircraft (leg spec + waypoint) is displayed in the info pane;
  • "OK" near the route field of the strip detail sheet means that the route could be parsed correctly, otherwise "!!" is displayed and info boxes will be showing destination (or nothing if unknown) instead of next waypoint.

Radio and communications

The FGCom version setting is the name of a subdirectory in resources/fgcom. See Notice file in that directory. FGCom version should be 3.4 (January 2015).

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, a growing list of text aliases exist ($wind, $qnh, $icao...) for both instant and preset chat messages. They automatically expand to the current value when message is sent. Have a look at the quick reference available from the help menu.

Resolving conflicts

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, the untouched FPL details will appear on next open.

Flight plan local–online 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).

Background drawings

You can map out procedures on your radar scope by extracting charts from the real documentation. The typical way would be to create one image file per published IAC/SID/STAR chart, named by procedure and including associated runways to make in-game selection easy. Turn the white background into transparency (e.g. with the command below; requires ImageMagick), and read the resources/bgdrawings/Notice file to learn how to add it to your airport sessions and position it on the radar screen.

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 are touched 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.

Strip exchange and OpenRadar interoperability

The strip exchange feature in ATC-pie is based on OpenRadar's 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;
  • a handover must be acknowledged by the receiver for the sender to lose ownership and all 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.

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

  • ATC-pie users can only hand over strips that are linked to a radar contact (no lone strip can be sent);
  • aircrafts 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.

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: Can I draw procedure routes?

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