Ground Services

From FlightGear wiki
Jump to navigation Jump to search
Ground Services
Started in 03/2017
Description Moving ground service vehicles at airports
Maintainer(s) ThomasS
Contributor(s) ThomasS
Status Under active development as of 03/2017
Topic branches:
fgdata (addon)

This article is about the GroundServices addon prototype for FlightGear. Unlike some existing ground services which are part of various aircraft, it is intended to be generic and not dependent on specific aircraft (though there will be dependencies from aircraft dimensions).


See also AI_Traffic#Ground_traffic_rendering for the modern approach to rendering ground traffic fast on both GPU and CPU.

The addon currently moves ground vehicles along an airports taxiways and provides simple catering and fueling services.

It is written completely in Nasal and is derived/inspired from the existing AI subsystem and tanker.nas (except for the way vehicles are moving).[1]

After starting FlightGear, GroundServices goes to "standby" mode, monitoring the distance of the main aircraft to the next airport. When the distance is below 3 NM (main.minairportrange), GroundService switches to "active" mode. It reads the corresponding groundnet.xml and ground vehicles are launched as defined in AI/groundservices.xml.

initialcount vehicles (scaled by airport size) of each type will be launched at their defined home location and move between the configured destinations (random groundnet nodes are used if nothing is configured).

When the distance to the airport exceeds 3 NM, GroundServices switches back to "standby" mode, removing all ground vehicles.

The models included are

The GUI provides the options to

  • Launch an additional vehicle (select in combo box and button "Launch")
  • Launch catering and fuel service for an arrived aircraft
  • Visualize the groundnet (which is implemented quite inefficiently by multiple models for each length due to the lack of dynamic model scaling). The color of the groundnet lines should be yellow, but differs for some unknown reason (lighting effects?) from red to orange.
  • Toggle auto movement of vehicles and auto service
  • Open a canvas map which shows the location of the vehicles and service points
  • Write the state of each vehicle to the logfile


There are already existing ground service components in FG providing Pushback, FollowMe, Ramp Marshall and Jetways (maybe even more). Integrating these with the existing AI system appears straightforward. Routes for driving vehicles on the apron could be derived from groundnet.xml.[2] The Nasal approach of tanker.nas however looks more comprehensive. Reading groundnet.xml from Nasal apparently isn't possible yet without doing explicit XML parsing. Though the airportinfo function in nasal provides parking and taxiway information, these might be derived from different sources than groundnet.xml.

Having the groundnet.xml information available in Nasal in combination with the logic in tanker.nas might provide a simple way for having vehicles moving on the apron.[3]


GroundServices was developed and tested with FlightGear 2016.4.3, 2017.3.1 and EDDKs, EHAMs, EGLLs and EDDFs groundnet. As of release 0.3.0 it is a FlightGear addon and so requires at least FlightGear version 2017.3. There are no further known special requirements and it should also work with later FlightGear versions and airports that have a groundnet defined.

The solution is based on the airports groundnet.xml. So for now you just have to make sure that your airports groundnet.xml is reasonable, meaning parking positions are at correct location and all connected to taxiways. Look at [1] for releases.[4]

Current Status

GroundServices currently moves ground vehicles along an airports taxiways and provides simple catering and fueling services. Its just a prototype and still might contain bugs. There is a risk of null/nil pointer incidents. Indicator for this is when all vehicles stop moving.

The catering and fueling services are composed of a catering vehicle approaching an aircraft right front door and a fuel truck approaching the left wing. The approach destinations are calculated from the aircraft position and a defined door and wing position of the aircraft. Currently the implementation only uses a rough approximation of these positions, because there seem to be only a few aircraft models out there that have door positions defined.[5]

Furthermore, there seems to be no way to get information about an AI aircraft model from the property tree currently. However, jetways.nas seems to find the door positions even for AI aircrafts (issue added to roadmap).

Known problems are (see also issue list):

  • Ground Services doesn't work with scenery outside FG_HOME (solved in release v0.3.0)
  • Vehicles appear twisting at some nodes when turning (partly solved in release v0.3.0)


The addon is available here. It is recommended to use the latest release 0.5.0 and install the addon from the zip archive.

Changelog up to release 0.5.0

v0.2.0 (August 2017):

  • Fixes the problem of vehicles having wrong elevation when they were launched before the scenery was completely loaded.
  • Uses position dependant elevation for visualized ground net segments instead of airport elevation.
  • Fuel truck added
  • Now finds a vehicle home position even for groundnets having inconsistent headings at parking positions
  • Fixes several "non-objects have no members" problems.
  • Delayed launch of initial vehicles
  • preparation for AI traffic integration

v0.3.0 (November 2017):

  • Further fixes for correct elevation of vehicles
  • Fix for airports with negative longitude (didn't work here)
  • Service points and schedules are introduced. Service points let catering and fuel trucks approach aircraft.
  • Canvas map shows location of vehicles, service points and main aircraft
  • Vehicles have varying speed (accelerate and brake)
  • The module is an addon now

v0.4.0 (April 2018):

  • Adjustments for complying to new addon structure

0.5.0 (June 2018):

  • Additional adjustments for complying to new addon structure. No more manual installation required.
  • Vehicles move at the outline of taxiways instead of on the center line. This reduces the number of visual collisions.
  • Two 737 model (Air Canada and Air France) and one Cessna Citation are launched. The Cessna will just move around the groundnet while the 737 will move to some non occupied neighbor position of the current aircraft.


As of release 0.3.0 this module is an addon and as of release 0.5.0 it fully complies to the FlightGear addon infrastructure available as of 2018.2.1. It is recommended to use at least release 0.5.0 of this addon with at least FlightGear 2018.2.1.

The addon is installed just like any other addon as described in Addon. No manual steps are needed any more.

A video of the installation and running can be found here:

Youtube video: Installation and running of Ground Services Addon for FlightGear


After starting FG with the aircraft located on an airport that has a groundnet defined (I propose using ufo on EDDK for a first attempt) the vehicles will start moving from their home point immediately. In EDDK vehicles will move near the main terminal and should be easily visible. EHAM, EDDF and EGLL are considerably larger and have no home configured. In EHAM vehicles will start from cargo position R, which is in the south west of the airport. Move ufo near there (by PHI; thats very easy) for seeing the vehicles.

If any problems occur, check FGs logfiles for nasal errors. In addition a logfile FG_HOME/groundservices.log is written by GroundService and can be checked for errors.


For having some nearby activity, two 737 models (Air Canada and Air France) will be launched after initialization (config parameter delayfornearbyaircraft). These will move to some non occupied neighbor position of the current aircraft and receive servicing.

Monitoring vehicles

Its not easy to detect the current position of ground vehicles. Seeing them from your current view point is mere chance.


Ground vehicles displayed in Phi

An option for monitoring vehicles is the map of Phi. This however requires two patches to the file Phi/topics/Map/AILayer.js in FG_ROOT. Near line 81 the type gsvehicle needs to added:

self.addData(self.aiPropsToGeoJson(data, [
  "tanker","gsvehicle", "aircraft", "multiplayer", "carrier" ], self._map.getBounds()));

and near line 139 these models need to be considered:

if (type == "gsvehicle") {
    callsign = child.getNode("id").getValue();
} else {
    if (type == "carrier") {

Don't forget the closing curly brace a few lines beneath (not displayed here). Reload Phi in your browser and choose "Other Traffic" in the layer selection menu.

Canvas Map

Ground Services map in EDDF

The map is opened by clicking the "Map" menu item in the Ground Services menu. It uses the following colored indicators for vehicles:

o ground vehicle
o active service point (arrived aircraft)
o current aircraft

Model Cockpit View

The addon Model Cockpit View lets cycle the view point through all AI cockpits. For using it with ground service vehicles, the phrase gsvehicle needs to be added manually to the code (main.nas):

  ~ ai.getChildren("gsvehicle")

By default, the view point will be at (0,0,0), so the view point from a ground vehicle will be exactly on the ground below the vehicle. Though this might be useful for analysis purposes, a raised view point is more interesting. See Model Cockpit View on how to change the view point.


The main configuration file is AI/groundservices.xml. When no home position is defined for an airport, the first (or last) parking node will be used as home.


Uninstallation is done by just deleting the addons directory and removing it from the addons option from the command line.

Implementation Notes

The groundnet information is stored in a graph data structure.

For simplification, the coordinates are projected to a 2D xy coordinate system, where all calculations are executed (The projection currently is a too simple linear projection).

Moving of vehicles is implemented by first finding a path along the graph (Graph.findPath()), which is quite simple due to Edsger Dijkstras preliminary work. The vehicles will move along their defined path like a train on rails. They will allways be fixed at some specific position on some edge (class GraphPosition).

For accomplishing a smooth transition from one edge to the other, the graph not only allows line edges but also arc edges. So the shortest path found through the graph will be smoothed (GraphUtils.createPathFromGraphPosition() and GraphUtils.createTransition()) by truncating line edges and connecting these by arc edges. These graph edges will be added temporarily to the graph and will be removed from the graph when the vehicle reaches its destination.

Smoothing the graph path is a quite complex process with many potential combinations (eg. short edges, small angles between edges, orientation of vehicles). Optimizing this process still is a work in progress.

Known Problems

Sometimes the errors

NasalSys.cxx:1204:Nasal runtime error: non-objects have no members
NasalSys.cxx:1216:  at /Users/thomas/Projekte/FlightGearGit/FGData/Nasal/canvas/api.nas, line 147

NasalSys.cxx:1204:Nasal runtime error: MapStructure model not found
NasalSys.cxx:1216:  at /Users/thomas/Projekte/FlightGearGit/FGData/Nasal/canvas/MapStructure.nas, line 27

are logged to the FG log file. The reason is unclear.


The list of possible improvements is endless. The following are some of the ideas (without any order):

  • The turning radius of vehicles at parking nodes is too small sometimes, which make vehicles turn unrealistically twisting Pending Pending
  • Vehicles should accelerate instead of just switching speed. 100}% completed Done Done
  • Vehicles shouldn't move on taxiways but on dedicated lanes. This requires either an extended version of groundnet.xml (newer versions of apt.dat might contain a groundnet for ground service vehicles) or some smart algorithm. In any case, a big challenge. Pending Pending
  • Vehicles not using dedicated lanes (currently all) should move at the outline of taxiways which reduces the risk of collisions. 100}% completed Done Done
  • Make a fuel and catering vehicle approach parking AI aircraft 100}% completed Done Done
  • Vehicles should be animated, starting with a catering vehicle moving up its container. Unfortunately the current catering vehicle model doesn't allow animation.Pending Pending
  • Animation of wheels. Pending Pending
  • Check using ai.nas mentioned in Scripted_AI_Objects. Pending Pending (that's actually outdated meanwhile, Ground Services looks much more promising)
  • Make it a Flightgear addon. 100}% completed Done Done
  • Add a canvas GUI for monitoring vehicles 100}% completed Done Done
  • Retrieve door positions from AI model like animated jetways does. AI aircraft should contain a piece of nasal code that adds door information to the property tree when loaded. However, extending AI core code for saving model origin information to the property tree could still be useful, eg. for defining cockpit positions in addon Model Cockpit View. 20}% completed
  • Extend AI core code for saving departure/arrival information of AI aircrafts to the property tree. Thus arrived parking aircrafts can be detected for service more reliably. Such an extension might also be helpful for the animated jetways. 10}% completed Pending Pending
  • Unify AI traffic categories for avoiding manual patches to Model Cockpit View and Phi by a Nasal registry for all kinds of AI/MP traffic, eg. AI.nas or Traffic.nas.[6] 10}% completed Pending Pending
  • Extend MapStructure.nas with a kind of layer registry for avoiding copying files into FG_ROOT.[7] . Latest tests show that no change to MapStructure.nas is required. The layer can just be added from the addon. Will be part of next release. 100}% completed Done Done


A followme vehicle on its way at EHAM.



  1. ThomasS  (Jun 2nd, 2017).  Re: .
  2. ThomasS  (Feb 1st, 2017).  Re: Ground services ! .
  3. ThomasS  (Feb 1st, 2017).  Re: Ground services ! .
  4. ThomasS  (Jul 28th, 2017).  Re: Ground services ! .
  5. ThomasS  (Jul 28th, 2017).  Re: .
  6. Hooray (Dec 2nd, 2017).  Re: Ground services ! .
  7. Hooray (Dec 2nd, 2017).  Re: Ground services ! .