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 Python3 for Qt5. It is therefore system-independant, but requires Python3 and its PyQt5 library to run. Otherwise, ATC-pie runs straight after download without any compiling (make, etc.) to do.

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.

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 Git repository:

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

I say again: the download/clone alone is not enough; both Python3 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:

• all airport sessions with a 3D tower view, FlightGear must be available, with the appropriate aircraft models and scenery data—note that it can run on a separate machine, as explained down this article;
• solo sessions with voice instruction recognition by the AI aircraft, install PocketSphinx (requires PyAudio);
• solo sessions with speech synthesis of AI pilots' radio messages, install pyttsx;
• FlightGear sessions with full ATC coordination, including unlimited strip exchange (recommended!) and CPDLC, install the Python IRC library;
• FlightGear and FSD sessions with realistic voice radio simulation, install the FGCom-Mumble plugin (requires a Mumble>=1.4 client);
• all sessions (except solo) with an ATC phone line switchboard, install PyAudio, plus PyMumble for FlightGear and FSD.

Running

Depending on your system and preference, you might be double-clicking, typing stuff or pulling your hair out. In any case what you must do is run a Python3 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 Python source files are associated with Python3.

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 views. This includes all tower and additional views, but does not affect the FGMS connection port, chosen on session start.	5009

Starting sessions

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 configuration options (⇧ Shift+F11), so it is preferable to configure them before starting the session to avoid undesired traffic at start.

FlightGear network session:

• callsigns for ATCs in FlightGear are expected to 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;
• you can connect multiple ATC-pie instances from the same computer, but you must use a different local port for each one;
• the three "sub-systems" that can be activated support different coordination features and differ in terms of interoperability with other clients, but all can be enabled together:
  • native ATC-pie coordination enables full interaction with other ATC-pie clients (except phone lines), plus CPDLC with FG aircraft;
  • ATC phone lines enables direct voice communications (telephone calls) with other connected ATC-pie clients;
  • OpenRadar handover compatibility implements OpenRadar's protocol to enable coordination with its users (will work with ATC-pie clients as a fallback if native sub-system not available), although some limitations apply (see interoperability note in the main article).

Configuring

Here are things you will soon want or have to set up for a regular use of ATC-pie:

• set up a tower view to enable visual contact with your traffic in AD sessions;
• for FlightGear and FSD sessions, give yourself a "social name" so that others recognise you when using any of the ATC coordination/exchange features;
• for a realistic radio experience in FlightGear and FSD sessions, set up FGCom-mumble, and test the configuration from the System menu.

If you intend to operate often at a given location, it is sensible to:

• if it is an airfield location, download the latest airport data file from the X-plane gateway and place it in CONFIG/ad (see the Notice file there);
• review and fill the various fields in the location set-up dialog (runway capabilities deserve special focus for more realisitc aircraft intentions in AD solo sessions);
• configure the workspace racks, bays and radar screens to suit the environment and service provided, they will be saved for future runs;
• if using the radar, pin your preferred navpoints (they are restored on every run) 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/Notice).

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

Airport scene rendering

Tower viewing, following a departing aircraft

A tower view allows you to overlook your airport and the connected or simulated traffic, like a controller from a tower viewpoint. It allows to choose from the tower positions specified in the source data if any (X-plane seems only to allow for one, but feel free to declare more for ATC-pie), otherwise defaults to somewhere over the airport to allow towering everywhere. It is disabled in CTR mode. There are two ways of activating a tower view. You may let ATC-pie start its own suitably configured FlightGear process, or have it connect to an external viewer manually set up to listen for traffic and accept telnet connections.

Running internally only requires FlightGear installed on your computer. A basic installation is enough, but you will need the scenery for your airport if you want anything exciting to see (and not sea!). Also, aircraft will only be drawn properly if the appropriate models are available. 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/Notice to understand how ATC-pie chooses models and liveries for its viewers. Aircraft and scenery locations can be filled in the System settings dialog if they are not in your FlightGear root directory.

Connecting to an external viewer allows to run FlightGear on a different machine and thereby relieve your session from the CPU load a local instance induces. If you want to do so, get a hint of the required positioning options you should start your viewer with, from the tower view tab in the system settings dialog. Of course, scenery, models and liveries must also be available to the running process.

In either case, once activated from the View menu, the tower view control pane is enabled, from which you can turn to runway points, follow selected aircraft... 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 to your session, for example placed around your airport for exciting camera footage of challenging landings. You will not be able to control those viewers from ATC-pie like the tower viewer, but you will be able to activate/stop the connection from the View menu. Additional viewers are registered by their host+port address, from the View menu at run-time or from a custom settings file (see CONFIG/Notice) read at start-up and on explicit reload (System menu).

Every such viewer registered on host XXX and port 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/Notice 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 procedures. The way to proceed is as follows:

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