How do I use FlightGear's UDP interface?

FlightGear uses UDP through its generic socket protocol or built-in native protocols. For most custom telemetry, cockpit hardware or 2 DOF motion projects, create a generic protocol XML file that maps property-tree values, launch FlightGear with a --generic=... option, and send or receive datagrams on the same address and port.

Which FlightGear UDP protocol should I use?

Use the generic socket protocol unless the external application already implements one of FlightGear's native binary packet formats.

Generic text packets are easier to inspect and less tightly coupled to a particular build. We recommend them for telemetry displays, data loggers, cockpit hardware and motion controllers. Native FDM is appropriate when another program actually replaces or drives the aircraft dynamics; first understand how FlightGear's flight-dynamics model updates the simulator.

How do I create a custom UDP protocol in FlightGear?

Create an XML file under FlightGear's Protocol data directory, define the properties and separators, then select that file with a --generic launch argument.

1. Choose the direction. Use out when FlightGear will transmit telemetry. Use in when an external application will write properties into FlightGear.
2. Choose a unique port and protocol name. The examples below use UDP port 5510 and the name fas-telemetry. Avoid ports already used by multiplayer, another FlightGear interface or another local process.
3. Create the output definition. Save the following as fas-telemetry.xml inside FG_ROOT/Protocol:

   <PropertyList><generic><output><line_separator>newline</line_separator><var_separator>,</var_separator><chunk><name>latitude</name><node>/position/latitude-deg</node><type>double</type><format>%.8f</format></chunk><chunk><name>longitude</name><node>/position/longitude-deg</node><type>double</type><format>%.8f</format></chunk><chunk><name>altitude</name><node>/position/altitude-ft</node><type>double</type><format>%.1f</format></chunk></output></generic></PropertyList>

   FG_ROOT, sometimes labelled FGData, is FlightGear's data package rather than the executable or per-user settings directory. If the file is not found, follow our guidance on identifying the active FlightGear data directory. Directory and filename case matter on case-sensitive systems.

4. Start a receiver. When both programs run on the same computer, bind the external application to 127.0.0.1:5510. A minimal Python diagnostic is import socket; s=socket.socket(socket.AF_INET,socket.SOCK_DGRAM); s.bind(('127.0.0.1',5510)); s.settimeout(5); print(s.recvfrom(4096)[0].decode()).
5. Launch FlightGear with the output option. Add --generic=socket,out,20,127.0.0.1,5510,udp,fas-telemetry through the launcher's extra-arguments facility or the fgfs command line. Our guide to adding and verifying FlightGear command-line options covers both methods.
6. Check the first datagram. The example produces a record resembling 51.47000000,-0.45000000,2500.0\n. Parse fields in exactly the same order as the XML chunks.

Keep a backup of every custom protocol file outside the installed data package. Replacing or updating FGData can remove local modifications, and reusing the name of a built-in protocol can create confusing version-dependent results.

What does the FlightGear --generic option mean?

The comma-separated fields define the transport, direction, processing rate, network endpoint and XML protocol name.

Do not insert spaces between fields. For output, the rate is a target rather than a guarantee; frame scheduling and system load can affect when packets are generated.

How do I connect a 2 DOF motion platform to FlightGear?

A 2 DOF platform normally receives FlightGear telemetry through a custom UDP output, while a separate motion-control application converts that telemetry into safe actuator commands.

First decide what the two degrees of freedom represent. A roll-and-pitch rig can use /orientation/roll-deg and /orientation/pitch-deg. Replace the chunks in the output XML with:

<chunk><name>roll</name><node>/orientation/roll-deg</node><type>double</type><format>%.4f</format></chunk><chunk><name>pitch</name><node>/orientation/pitch-deg</node><type>double</type><format>%.4f</format></chunk>

FlightGear's attitude values are not actuator positions. The motion controller must apply axis mixing, scaling, filtering, travel limits and a return-to-neutral or washout strategy. Mapping sustained aircraft pitch or roll directly to an actuator can leave the platform pinned at its mechanical limit.

• Use an independent emergency stop. It must not depend on FlightGear, UDP or the motion-control computer.
• Implement a packet timeout. Stop or return safely towards neutral when fresh telemetry stops arriving.
• Clamp travel, speed and acceleration. Enforce limits in the hardware controller as well as the application.
• Test without a person aboard. Verify axis direction, neutral position and limit behaviour at reduced output first.

If the platform represents a different pair of axes, such as pitch and heave, choose properties that match the controller's cueing design rather than assuming roll and pitch are universal. Aircraft-specific properties should be checked in FlightGear's property tree before being added to the XML.

How do I send controls into FlightGear over UDP?

Use a separate generic input definition and a different port, then send one complete control record per datagram.

Save this example as fas-controls.xml in the same FG_ROOT/Protocol directory:

<PropertyList><generic><input><line_separator>newline</line_separator><var_separator>,</var_separator><chunk><name>aileron</name><node>/controls/flight/aileron</node><type>double</type></chunk><chunk><name>elevator</name><node>/controls/flight/elevator</node><type>double</type></chunk></input></generic></PropertyList>

Add --generic=socket,in,20,127.0.0.1,5511,udp,fas-controls alongside the output option. The external application can send a test record with import socket; socket.socket(socket.AF_INET,socket.SOCK_DGRAM).sendto(b'0.10,-0.20\n',('127.0.0.1',5511)).

Aileron and elevator values normally use the range -1 to +1. Throttle values commonly use 0 to 1, but multi-engine and aircraft-specific systems can expose separate nodes. Inspect the selected aircraft's property tree rather than assuming one throttle path fits every aircraft.

If a value arrives but immediately returns to its previous value, another part of FlightGear is probably writing the same property. Joystick bindings, autopilots and aircraft systems can overwrite a generic input on the next simulation frame.

What must the external UDP application handle?

The external application must validate records and cope with UDP packet loss, duplication and reordering.

• Keep one complete record in each datagram. Do not divide a line across packets or assume UDP behaves like a byte stream.
• Match the XML exactly. Field order, separator, numeric format and line terminator must agree. One omitted field shifts every value after it.
• Reject unsafe values. Check the field count, conversion result and permitted range before applying incoming controls or motion commands.
• Use freshness checks. Add a sequence value or timestamp when the application requires stale and out-of-order packets to be detected.
• Keep packets reasonably small. Very large property lists can be fragmented at the IP layer, making the whole record more likely to be lost.
• Treat UDP as unauthenticated. Keep control and motion ports on loopback or a trusted local network rather than exposing them directly to the Internet.

UDP is well suited to continuously refreshed telemetry and controls because a newer record can replace a lost one. For an action that must happen exactly once, add application-level acknowledgement and duplicate detection or use a connection-oriented interface.

Why is FlightGear UDP not sending or receiving data?

Most failures are caused by the wrong direction, an undiscovered XML file, an incorrect address, a port conflict or a parser that does not match the protocol definition.

For two-computer installations, the UDP firewall, port and routing checks used for FlightGear networking also apply. Keep custom-interface ports separate from multiplayer ports so traffic and troubleshooting remain unambiguous.