ATC-pie installation guide

This article is about installing and configuring ATC-pie. For a manual on how to use it, see ATC-pie user guide.

Installing

ATC-pie is free and open source, and programmed in Python for Qt5. It is therefore system-independant, but requires Python and PyQt5 to run. Otherwise, ATC-pie runs straight after download without any compiling (make, etc.) to do. The easiest way to get the latest stable ATC-pie version is to:

1. download the package from the project page;
2. extract the files to the directory of your choice.

I say again: this download alone is not enough; both Python and PyQt5 must be installed too. The exact dependencies and required versions are listed in the README file packed in the download.

At this point you have a working program. But further software pieces can be installed to enable more of its features, as listed below. Depending on your use of ATC-pie, they can be recommended for more realism but they are not required, and can be installed later. Also read the README file for extra notes on installation.

To enhance:

• airport mode with 3D views (incl. tower view), FlightGear must be available with the sufficient ACFT and scenery data (it can run on a separate machine, as explained down this article);
• solo sessions with voice instruction recognition by the AI aircraft, install PyAudio and PocketSphinx;
• solo sessions with speech synthesis of AI pilots' radio messages, install pyttsx;
• FlightGear sessions with full ATC coordination (incl. unlimited strip exchange, phone lines...) and CPDLC, install the Python irc library;
• FlightGear and FSD sessions with realistic voice radio simulation, set-up the FGCom-mumble plugin (requires a Mumble>=1.4 client);
• all sessions (except solo and playback) with integrated ATC phone lines, install PyAudio (FlightGear sessions also require the Pyhton irc library).

Running

Depending on your system and preference, you might be double-clicking, typing a command or pulling your hair out. In any case what you must do is run a Python interpreter on the ATC-pie.py file from the downloaded directory.

Tip for Windows users: create a shortcut whose "target" is cmd /k Z:\path-to-pie\ATC-pie.py, making sure "start in" is set to the same Z:\path-to-pie and that .py files are associated with Python.

Two program modes

Initial graphical launcher, with AD vs. CTR mode choice

On program start, a welcome launcher window should open, from which you may start a session in either airport (AD) or centre (CTR) mode, i.e. respectively with or without a base airfield.

The airport mode is for ATC positions like approach or tower control, or any combination of those. In this mode, ATC-pie centres the radar at the chosen base airfield, depicts its tarmac and runways, and enables features like a tower view and active runway selection.

The centre mode is designed for en-route control centre simulation. It disables all airport-specific features, and allows to place the radar anywhere on Earth. When selecting this mode:

• The location code is a designator of your choice (excluding airport codes), under which to save your location-specific settings. A good idea is to use ICAO airspace designations, e.g. SBBS for the Brasilia FIR in central Brazil or LFFF for the Paris region in France.
• The radar position field specifies the point on which to centre the radar. For example, LFPO>090,15 will centre the radar on a point 15 NM to the East of Orly airport. Click on the help button for a summary of valid point specification formats, or read the Point specification section in the quick reference for more detail.

Command line arguments

You may bypass the launcher and start directly at a given location with the following command, using an ICAO code for an airport or a previously defined CTR location code:

./ATC-pie.py location_code

Besides, the following command line options are available:

Option	Effect and argument specification	Default
--map-range=range	Only valid with a location code argument. Defines the distance in NM from the radar centre up to which the map will be drawn and navpoints listed in the navigator (accepted values are 20..500). This does not affect radar range, which can still be greater or lower, and be changed within sessions.'	100 in AD mode; 300 in CTR mode
--views-send-from=port	Sets the local UDP port number to bind for sending FGMS packets to FlightGear viewers. This includes tower and additional viewers, but does not affect the FGMS connection port, chosen on session start.	5009

Starting notes by session type

All session types are started from the System menu.

Solo simulation:

• wind will be randomised at start, but will be forced to blow in a favourable direction if at least one active runway is selected before start;
• traffic is spawned with intentions according to the solo simulation options (⇧ Shift+F11), so it is preferable to configure them before starting the session to avoid undesired traffic at start.

FlightGear network sessions:

• ATC callsigns would usually start with the ICAO code of the controlled airport or sector, and end with a hint on the provided service (twr, gnd, ctr...), e.g. "KORDgnd" (note that FGMS restricts callsign length to 7 characters);
• before choosing your callsign, make sure it is not already in use;
• the four "sub-systems" that can be activated support different features and differ in terms of interoperability with other clients, but all can be enabled together:
  • native ATC-pie messaging: enables full interaction (except phone lines) with other ATC-pie clients, plus CPDLC with aircraft;
  • FGCom-mumble radio: is the realistic FlightGear radio system—leave unticked if using an external software for radio;
  • ATC phone lines: enables direct voice communications (telephone calls) with other connected ATC-pie clients;
  • OpenRadar compatibility: enables coordination with OpenRadar clients (limitations apply)—also works as a fallback between ATC-pie clients if native sub-system not available.

FSD network sessions:

• to allow more accurate transponder simulation and to render the correct ACFT models in your FG views, ask connecting pilots to prefix their "real name" string with the ICAO type designator of their aircraft and their best XPDR mode, separating the fields with / and //—for example: "C172/C//Joanna Doe" or "B772/S//Jo User" (XPDR modes: A, C, S, or 0 for none);
• if you enable Hoppie ACARS, make sure you set your account to log on the "None" network, and that you start with an unused callsign;
• text radio tunes to the frequency publicised from the radio panel, so make sure you set it if you wish to use text communication;
• note that with the FSD protocol:
  • transponders are not fully capable of mode S (GND, IAS and Mach will never actually be reported);
  • opening/closing flight plans is not supported (besides, with the historic protocol, FPLs can only be filed/amended by the pilots).

Configuring

The most important things to set up for realistic sessions with ATC-pie:

• for GND and TWR positions: a tower view to enable visual contact with your traffic;
• FlightGear and FSD sessions: FGCom-mumble for the radio experience.

If operating regularly at a given location, consider the following:

• if it is an airfield, download the latest ".dat" file from the X-plane gateway and place it in CONFIG/ad (see the README file there);
• review the various fields in the location set-up dialog (example: setting runway capabilities right will result in more realisitc aircraft intentions during solo AD sessions);
• configure the workspace racks, bays and radar screens to suit the environment and service provided (they will be saved for future runs at the same location);
• if using the radar, pin your preferred navpoints (they are restored on every run at the same location) and consider creating/importing background pictures to map terrain obstacles, procedure charts, etc. (see section below);
• for solo and teacher sessions at airports especially, build an elevation map (see CONFIG/elev/README).

For more advanced editable options, read the CONFIG/README file.

Airport scene rendering

Tower viewing, following a departing aircraft

A tower view allows to overlook the airport and the traffic, like a controller from a tower viewpoint (the feature disabled in CTR sessions). ATC-pie allows to choose from the tower positions specified in the source data, or custom ones specified in the local viewpoint settings, or defaults to somewhere over the airport. There are two ways of activating a tower view: let ATC-pie start its own internal FlightGear process, or have it connect to an external viewer manually started.

• Running internally only requires FlightGear installed on your computer. A basic installation is enough, but you will need the appropriate scenery and aircraft models. In FlightGear sessions, the models required are those flown by the pilots. For all other session types, models are chosen according to the ICAO type designators of the aircraft and the specifications in icao2fgfs. Read CONFIG/acft/README to understand how ATC-pie chooses models and liveries for its viewers. Aircraft and scenery locations can be filled in the viewer settings dialog if they are not in your FlightGear root directory.
• Connecting to an external viewer allows to run your own FlightGear instance separately, for example on a more powerful machine. If you want to do so, get a hint of the required positioning options you should start it with from the viewer settings dialog. Of course, scenery, models and liveries must also be available to the running process.

In either case, once activated from the System menu, the tower view control panel is enabled, from which you can turn to runway points, follow selected aircraft, etc. Direct FlightGear input in the view window is also possible: right click and drag allows to look around, x and ⇧ Shift+x change the zoom level, etc.

You can hook up additional viewers in the viewer settings dialog, each registered with a host+port address. You will not be able to control those viewers from ATC-pie like the tower viewer, but you will be able to activate the connections individually. A viewer registered with XXX:YYY should be running on XXX and started with options --multiplay=out,TTT,HHH,PPP and --multiplay=in,TTT,,YYY, where:

• HHH is the host on which ATC-pie is running;
• PPP is the default 5009, or the chosen port number if ATC-pie was started with --views-send-from;
• TTT is the network polling frequency (100 is common practice; change as desired if you know what you are doing).

Background images

Pixmap image example with a terrain map around LIMW (Aosta, Italy)

Text-specified drawing example with procedures for LSGG (Geneva, Switzerland)

Background images allow to decorate:

• radar scopes, e.g. to display procedure routes or airspace boundaries;
• loose strip bays, to work the strips over custom backgrounds, e.g. an airport ground chart.

There are two ways to create a background. One is to import a picture (pixmap file like JPEG or PNG, including transparency); the other consists in writing a drawing specification file to paint coloured lines, points and text labels (for radar backgrounds only). See CONFIG/bg/README to learn how to import and draw background images.

For example, you can map out procedures (SID, STAR, IAD...), grouping them by associated runways so they toggle together on the radar. Drawings are generally appropriate for that because they avoid manual positioning by directly referring to the points named in the published procedures. But if you want more than schematic line plots and text labels, you should create the picture yourself, for example using an image processing tool like GIMP and a transparent layer over a real map canvas or a screenshot of your ATC-pie radar with pinned navaids as landmarks.

If you have a sector file of the format used in VATSIM/IVAO (.sct) for your area, you should try to import it with the provided extraction tool. It will retrieve most of the contents around the open location up to the current map range, and translate it to ATC-pie's native drawing format, although the generated files always require some filtering and post-editing. If you know they are included, it is generally the best option for things like SID/STAR drawing. To do so:

1. Run the "extract drawings from sector file" option (System menu) and select the file to extract from. This generates the following files in the OUTPUT directory:
   • ICAO.lst.extract, a menu file for the generated drawings;
   • bg-ICAO-*, the extracted drawings in the ATC-pie format;
   • bg-extract.err, a log of the errors detected in your sector file (do not be alarmed as they often contain many).
2. Import the results:
   • move or copy-paste lines from ICAO.lst.extract to CONFIG/bg/ICAO.lst;
   • move the desired drawing files under CONFIG/bg, adjusting the paths in the .lst menu as you organise subdirectories.
3. Post-editing (cleaning)

   ATC-pie does its best to understand the objects in the sector file and to group things together depending on their type. But not everything can be guessed automatically. This last step is where you filter, merge and split objects, rename points, change colours, etc. to your liking.

   Each generated drawing section (point list under a colour) is automatically labelled with the line number where it was sourced from in the sector file so you can easily trace it (@nnn). A tool like sed will help you get rid of all these unwanted suffixes once you have sorted and renamed your objects:

   sed -ri 's/ +@[0-9]+$//' file_to_clean

NB: ATC-pie does not package or source from sector files directly because their data is not free. Besides, a lot of it is usually redundant with the airport sources.

Tips:

• You can check your image configuration without restarting the program, by reloading the files in their current state from the System menu (Alt+F12).
• The "image positioning helper" allows to move and resize imported pictures, adjusting the corners visually rather than programmatically if you have no specification for them. All visible pixmap images will be moved simultaneously, so you can work with several at a time if you want to. On dialog box close, a file is generated in the OUTPUT directory for you to copy from.
• An OpenStreetMap option will take you to the free online map server, centred on your radar centre position. For a quick and dirty start (e.g. for access to coastlines, borders and rivers) you can screenshot the map and use it as a background.