How do I use FlightGear's UDP interface?

FlightGear exchanges UDP data with external applications through its generic socket protocol or built-in native protocols. For most projects, define the required property-tree values in a generic protocol XML file, start FlightGear with a --generic=... option, then have the external program send or receive datagrams on the matching address and port.

Which FlightGear UDP protocol should I use?

Use the generic protocol unless your application already implements FlightGear's native binary packet structures. Generic UDP is readable, configurable and less tightly coupled to a particular FlightGear build.

Native packets are compact but not self-describing. A structure mismatch can produce believable-looking yet completely wrong values, so generic text packets are safer for telemetry panels, hardware interfaces, data loggers and small control applications. If you are replacing the aircraft dynamics, first understand how FlightGear's flight-dynamics models update the simulator.

How do I send FlightGear telemetry over UDP?

Define output chunks for the properties you need, select an unused UDP port, and make the external application listen on that port.

1. Choose stable properties. Common telemetry nodes include /position/latitude-deg, /position/longitude-deg, /position/altitude-ft, /orientation/roll-deg and /orientation/pitch-deg. Aircraft-specific systems may use different or dynamically created nodes.
2. Create the protocol definition. Save a file such as fas-telemetry.xml in the Protocol directory under FlightGear's data root, normally called FG_ROOT. Directory case matters on case-sensitive systems, and the simulator's executable directory is not necessarily its data root. Keep a separate copy because reinstalling or replacing the data package can remove custom files.

A minimal three-value output definition is:

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

1. Start the receiver first. Bind the external program to 127.0.0.1:5510 when both programs run on the same computer.
2. Start FlightGear with the output option. Add --generic=socket,out,20,127.0.0.1,5510,udp,fas-telemetry through the launcher's additional-options field or the command line. The fields specify socket transport, output direction, 20 updates per second, destination address, destination port, UDP and the protocol filename without .xml. Our guide to FlightGear startup options explains where these arguments fit.
3. Parse each datagram in chunk order. The example produces a packet resembling 51.47000000,-0.45000000,2500.0\n. UDP preserves packet boundaries, but it does not guarantee delivery or ordering.

A minimal Python receiving test is import socket; s=socket.socket(socket.AF_INET,socket.SOCK_DGRAM); s.bind(('127.0.0.1',5510)); print(s.recvfrom(4096)[0].decode()). It blocks until one datagram arrives, which makes it useful for separating a FlightGear configuration problem from a problem in the main application.

How do I send controls into FlightGear?

Use a second UDP port and a generic input definition containing writable control properties. Separate input and output ports make packet direction clear and avoid binding conflicts.

For example, an input file named fas-controls.xml can contain:

<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 program can then send a packet 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 inputs normally use a range from -1 to +1. Throttles commonly use 0 to 1, but multi-engine aircraft and aircraft-specific systems may expose separate nodes. A joystick, autopilot or aircraft system can overwrite an input property on the next simulation frame; inspect the property tree if the value arrives but will not remain set.

UDP suits continuously refreshed controls because the next packet replaces a lost one. For commands that must be processed exactly once, add sequence numbers and acknowledgements at application level or use a connection-oriented interface.

Why is FlightGear UDP not sending data?

Most FlightGear UDP failures come from a reversed direction, an undiscovered protocol file, the wrong address or a parser that expects a different packet layout.

• Check in and out. With out, FlightGear sends to the listed destination. With in, FlightGear opens the local receiving endpoint.
• Omit .xml from the option. A file named fas-telemetry.xml is selected as fas-telemetry.
• Confirm the data root. Placing the file beside the FlightGear executable is a common mistake. Check the startup log for protocol-loading or file-not-found errors.
• Test on loopback first. 127.0.0.1 works only when both applications are on the same machine. For two computers, use the receiving computer's LAN address and allow the chosen UDP port through its firewall.
• Match the XML exactly. The receiver must expect the same chunk order, separator, numeric representation and newline terminator. An extra field shifts every value after it.
• Avoid port conflicts. Only one process can normally bind the same local UDP address and port unless it deliberately enables socket sharing.
• Keep packets small. Huge property lists can trigger IP fragmentation, which makes loss more likely. Split large telemetry sets or lower their rate.

Remote-machine problems are usually ordinary UDP routing or firewall issues rather than FlightGear protocol faults. The port and firewall checks in our FlightGear UDP networking troubleshooting apply here as well, although external-application ports should be kept separate from multiplayer ports.