ATC-pie installation guide

From FlightGear wiki
Jump to navigation Jump to search

Installing

Preparing

ATC-pie is free and open source, and programmed in Python3 for Qt5. It is therefore system-independant, but requires Python3 and the PyQt5 library to run. The exact dependencies and required versions are listed in the README file packed in the download. When they are installed, ATC-pie runs straight away without any compiling to do (make, etc.).

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.

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

More to install?

I say again: the download/clone alone is not enough; both Python3 and PyQt5 must be installed too. Please read the README file for extra notes on installation.

With the dependencies installed, 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.

For a 3D tower view in any airport session, 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.

To enhance solo sessions:

  • with voice instruction recognition by the AI aircraft, install PocketSphinx;
  • with speech synthesis of AI pilots' radio messages, install pyttsx.

To enhance FlightGear and FSD sessions with an integrated ATC telephone switchboard (direct voice lines), install PyMumble.

To enhance FlightGear sessions:

  • with CPDLC and full ATC coordination including unlimited strip exchange and text messaging, install the Python IRC library (recommended!);
  • with voice radio simulation, install the FGCom-Mumble plugin (requires a Mumble>=1.4 client) or the older standalone FGCom executable client (note that both variants cannot be used simultaneously).

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.

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. In this mode, ATC-pie places the radar at the chosen base airfield, depicts its tarmac and runways, and enables features like tower viewing and 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 more than one ATC-pie instance from the same computer, but must use different ports;
  • 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, but does not currently operate with other software;
    • ATC phone lines system integrates direct voice (telephone) lines to other connected ATCs in the ATC coordination panel (also ATC-pie only);
    • OpenRadar handover compatibility implements OpenRadar's native system to enable coordination with its users, 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 FlightGear sessions and realistic radio experience, select an FGCom variant in the system settings, 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 / Shift+x keys 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 topographic map shot around LIMW (Aosta, Italy)
Hand drawing example with procedures for LSGG (Geneva, Switzerland)

Background images allow to decorate:

  • radar scopes, with all sorts of maps and useful information about the airspace, terrain or procedures;
  • loose strip bays, to move unracked strips over custom backgrounds, e.g. ground charts of the airport.

There are two ways to create backgrounds in the program. One for all purposes is to import pictures (pixmap files like JPEG or PNG, including transparency); the other for radar backgrounds consists in writing drawing specification files to paint coloured lines and labelled points. This allows to import anything from complex coloured height maps to schematic airspace outlines. The CONFIG/bg/Notice file explains how to import and draw background images.

For example, you can map out procedures (SID, STAR, IAD...), grouping them by associated runways. Drawings are generally appropriate for that because specifications allow to directly refer to named points as per the published procedures, and therefore avoid manual positioning. But if you want more than schematic line plots, you should create the picture yourself. Using an image processing tool like GIMP, superimpose a transparent layer on top of a real map canvas, or over a screenshot of your ATC-pie radar with pinned navaids as landmarks, and freely decorate your picture.

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 "extract drawings from sector file" System menu tool. It will extract most of the contents around the open location up to the current map range, and translate it to ATC-pie's native drawing format. If you know they are included, it is generally the best option for things like SID/STAR procedures, although the generated files always require some filtering and post-editing. 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 (GPL).

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.