fgms 0.11.8
The
FlightGear MultiPlayer Server
project
page_overview.cxx
Go to the documentation of this file.
1  /**
2  * \page overview Overview
3  *
4  * \ref fgms is an UDP packet relay server that powers the \ref FlightGear \ref mp_network.
5  * - its written in c++
6  * - is licensed under the <a href="COPYING.html">GPL</a>
7  * - the current production version is the <b>0.x</b> series which is considered stable
8  *
9  *
10  * \image html fgms.1.png
11  *
12  * A typical \ref fgms server running will:
13  * * Listen for UDP traffic on port 5000 which are either
14  * - An \ref fgfs client with a pilot
15  * - Or other fgms servers in a relay relationship
16  * - Traffic from local pilots is forwarded to the other fgms servers ie \ref conf_relays.
17  * - Traffic from other pilots/relays is forwarded to local pilots, if within range.
18  * * If configured, <b>all</b> UDP packets are forwarded to the \ref conf_crossfeed port
19  * * If the tracking is enabled (see \ref tracker)
20  * - A \ref tracker_client is started as a a process thread. This forwards information via tcp
21  * to the \ref tracker_server
22  * - The \ref tracker_server can be either local, or at another location on the internet. It
23  * is a seperate application that has to be run.
24  * * Port 5001 is a tcp \ref telnet_port for getting status information
25  * \note
26  * And important aspect is missing from the above.
27  * - Packets are only forwarded to players who are within range of each other in the simulator
28  * - eg A pilot physically in London and another in Tokyo are flying above Paris and see each other
29  * - This substantially reduces traffic, see \ref server_out_of_reach
30  *
31  *
32  *
33  *
34  * \section paris_1 1: Between FGFS and FGMS - UDP:5000
35  *
36  * - An \ref fgfs sim session can choose to connect to ANY instance of FGMS on the \ref mp_network
37  * - Below is one connection, in this case to a FGMS which has the \ref server_is_hub attribute true
38  * - but can be to ANY instance of FGMS.
39 \code
40  /----\ /----\
41  | | Flight Data - 10 Hz | |
42  | | >>>>>>>>>>>>>>>>>>>>>> | |
43  |FGFS| Nearby Flights - 10 Hz |FGMS|
44  | | <<<<<<<<<<<<<<<<<<<<<< |*HUB|
45  | | | |
46  \----/ \----/
47 \endcode
48  *
49  * * These are raw packets of \ref xdr encoded binary data consisting of a
50  * header, positions data, and various property tree values, including the CHAT messages.
51  * * A typical packet is about 800 bytes long, with a maximum packet length (I think) of 1200 bytes.
52  * * As recently indicated now that FGFS has extrapolation code to continue the aircraft
53  * movement even in the absence of position packets
54  *
55  * \note Nominal 10 Hz is too frequent and 2 to 4 hz is sufficient
56  *
57  * @see FG_SERVER::SetHub(), \ref server_is_hub
58  *
59  * \section paris_2 2: Between two instances of FGMS - UDP:5000
60  *
61  * Packets between FGMS and configured FGMS \ref conf_relays
62  * - in this case to a RELAY that has the HUB attribute set.
63  * - LOCAL means a FGFS instances connected to that particular FGMS.
64 \code
65  /----\ /----\
66  | | LOCAL Flights - 10 Hz | |
67  | | >>>>>>>>>>>>>>>>>>>>>> | |
68  |FGMS| Nearby Flights - 10 Hz |FGMS|
69  | | <<<<<<<<<<<<<<<<<<<<<< |*HUB|
70  | | All Flights - 1 Hz | |
71  \----/ <<<<<<<<<<<<<<<<<<<<<< \----/
72  (Lazy Relay)
73 \endcode
74  * If ALL other FGMS instances RELAY to the FGMS with HUB attribute, then they need
75  * not RELAY to other instances, and will receive ALL Flight information
76  * at a slower rate, 1 Hz.
77  *
78  * @see \ref conf_relays, FG_SERVER::AddRelay(), FG_SERVER::SendToRelays()
79  *
80  * \section paris_3 3: Other connections supported by FGMS
81  *
82  *
83  * \subsection paris_crossfeed (a) CROSSFEED Port - UDP:3333
84  *
85 \code
86  /----\ /-----\
87  | | | |
88  | | | |
89  |FGMS| All Flights - as recd |CROSS|
90  | | >>>>>>>>>>>>>>>>>>>>> |FEED |
91  | | | |
92  \----/ -\-----/
93 \endcode
94  * * Since CROSSFEED receives ALL raw packets as
95  * received by that instance of FGMS it has ALL
96  * Flight information, and can offer various
97  * forms of output of that data, filtered or unfiltered.
98  * * One offered presently on a HTTP port is a
99  * json string reply. Since REMOTE packets only
100  * arrive at 1 Hz, this sting is only updated
101  * each second.
102  * * CROSSFEED can also filter these packets for
103  * 'movement' - positions, altitude, heading,
104  * speed change, and write the results to
105  * a PostgreSQL database. That is 'replace'
106  * the following 'tracker' port.
107  *
108  * @see \ref conf_crossfeed, FG_SERVER::AddCrossfeed(), FG_SERVER::SendToCrossfeed()
109  *
110  * \subsection paris_tracker (b) TRACKER Port - UDP:8000
111  *
112  \code
113  ---------------------------
114 
115  /----\ /-----\
116  | | | |
117  | | LOCAL Flights as recd. | |
118  |FGMS| >>>>>>>>>>>>>>>>>>>>>> |TRACK|
119  | | PING/PONG - alive msg |SERV.|
120  | | <<<<<<<<<<<<>>>>>>>>>> | |
121  \----/ -\-----/
122  \endcode
123  * Inside FGMS these messages are transferred
124  * from the FG_SERVER module to the FG_TRACKER
125  * module via an IPC.
126  *
127  * The unfiltered LOCAL Flight messages are
128  * of three types -
129  * CONNECT - When a new FGFS connects to FGMS
130  * POSITION - Messages as the flight continues.
131  * DISCONNECT - Final message when flight expires.
132  *
133  * The Tracker Server posts these (unfiltered)
134  * messages to a PostgreSQL database.
135  *
136  * No protocol other than the PING/PONG - are
137  * you alive - messages. All data is in form of an
138  * ASCII string.
139  *
140  * This requires each FGMS to actively connect
141  * to the tracking server.
142  *
143  * @see \ref tracker, \ref conf_tracker, FG_SERVER::AddTracker()
144  *
145  *
146  * \subsection paris_telnet (c) TELNET Port - TCP:5001
147  * This control port is presently only used to
148  * provide a list of current flights.
149 \code
150 
151  /----\ /-----\
152  | | | |
153  |PC | Flight List | |
154  \----/ <<<<<<<<<<<<<<<<<<<<<< |FGMS |
155  |....| (LOCAL and REMOTE) | |
156  \----/ | |
157  \-----/
158 \endcode
159  * Provides a list of all flights, marked as
160  * LOCAL or REMOTE (with server name).
161  * It can be a heavy load on the FGMS instance
162  * if this is done frequently. For each request
163  * a fork() (or thread) process is started to
164  * attend to the reply.
165  *
166  * No protocol, other than the single shot
167  * telnet connection. Data flows only from FGMS
168  * to the Telnet establisher.
169  *
170  * The telnet port is a simple way to query the server and get some data including list of pilots. eg
171  * \code
172  * > telnet mpserver14.flightgear.org 5001
173  * \endcode
174  * @see \ref telnetport setting, FG_SERVER::SetTelnetPort, FG_SERVER::HandleTelnet
175  *
176  *
177  * \subsection next_dd Next >
178  * * The \ref mp_network
179  *
180  */