FDM engine feature standardization

Request for Comments:

FlightGear Run Levels SGModule - standalone SGSubsystems An Integrated AI Traffic System Autopilot Enhancements Backwards Compatibility Initiative CDI instrument Decoupling the AI Traffic System Multiplayer Enhancements Modularizing, parallelizing and distributing FlightGear FDM engine feature standardization FlightGear Headless FlightGear Sessions Keyboard function priority list Next Generation Scenery Property Tree Reorganization Recommended Property Tree Enhancements Recommended Project Policies Redesigning the Replay System Remote Properties Simplifying Aircraft Deployment

External FDMS

To learn more about implementing your own external FDM using the FGNetFDM structure, please see PropertyTree:Sockets#Using_Proprietary.2FExternal_FDMs.

Intro

Currently, the main FDM engines supported by FlightGear (JSBsim & Yasim) provide support for various different features which can be considered to be essential for a realistic high-fidelity simulation of aircraft in FlightGear, some of which may however not yet be sufficiently supported by one or both FDM engines, or which are simply not yet provided in a standardized fashion, so that explicit workarounds need to be made in FlightGear to accommodate the requirements of each individual FDM engine.

It is the goal of this page to identify such areas in JSBsim and YaSim to ensure that both engines can start working on providing such essential functionality in a generic and portable fashion that can be easily leveraged by FlightGear without relying on workarounds.

Please also see The Re-/Initialization Process in FlightGear: A Specification Proposal and FlightGear Sessions for a more in-depth discussion about the rationale behind this.

Status (05/2013)

it appears that orientation/side-slip-deg and side-slip-rad don't have the same sign, depending if it's a yasim or a jsbsim plane. is there a commonly adopted convention for this property? — jean pellotier

On a related note, I've been wondering whether we should start the sim with the engines running when starting from a runway. Being on the runway with the engine off isn't particularly realistic. If we were feeling particularly keen also having the altimeter set and the radios tuned to the tower frequency might be nice. Ah, that's a much more contentious one. The problem, from my point of view, is that our -set.xml files only encode one aircraft state (usually cold-and-dark). To encode (accurately) engines-running or in-flight as the start state, needs some kind of profile system where properties can have different values, and XML / Nasal can be initialised differently. That would make nice in-air starts possible (gear already up, throttles at sane position), as well as offering 'cold, dark and parked' or 'on the active and ready to go' as options. (And end all the per-aircraft 'auto-start' menu options - since they'd become standardised). — James Turner

Unfortunately the underlying FDMs (JSBSim and Yasim) also have some limitations in this area - some won't correctly trim the aircraft unless it starts on the ground and stationary. Thorsten Brehm has done some improvements in this area but you still need to experiment to find all the settings for a particular aircraft, unfortunately. The real solution is each aircraft needs some additional code, which represents the 'in-air' state, or at least some sensible values) - engines running, gear up, fuel pumps on, etc. And then we need a way to request that state. This would be a fairly major addition, but it's something to consider after the next release. — James Turner

Once 2.10 has branched (i.e, in a month!) I'm going to make a consistency change to a simulation variable: namely to change the body (UVW) accelerations JSBsim exposes to FlightGear, to come from a slightly different source (FGAccelerations::GetUVWdot instead of FGAccelerations::GetBodyAccelerations). This is because the later includes gravity and some other terms (centripetal acceleration, I'm guessing, but I'm not an expert) which the YASim equivalents do not. I'm also going to expose the values via new properties under /accelerations/body/foo-accel-fps_sec, for both JSBSim and YASim. This will enable standard simulation of inertial acceleration based instruments, which I want to play around with. Because of the current discrepancy between JSBSim and YASim, the body accelerations are currently *not* exposed in any standard location (JSBSim exposes them in its private property tree), and code is avoiding using them — James Turner

List

The following list should eventually represent a fairly complete collection of technical requirements and individual features that are either only met/supported by one single FDM engine, or that are not yet fully or properly supported by any one of them at the moment.

Note: If you are aware of any other relevant restrictions or items that should be added here, please do feel free to make corresponding augmentations!

Constraining Property Tree Access

According to a discussion on the jsbsim developers' mailing list in 05/2009 [1], there needs to be a formal decision, whether FDMs (or any other FlightGear subsystems that may at some point be considered standalone entities for that matter) should generally be 'allowed' to publish state outside their own fdm subtree, or whether they should be constrained to just their branch of the property tree. Some of the arguments that were presented include:

Pro

• "I don't see any reason for not putting them into an arbitrary location in the property tree - until it's defined as illegal"
• "I don't think it is a good idea to have two properties updated for the same purpose - the automatically created from the components name and one from the output element."
• "Currently there is no explicit note, that components shall not be named outside the jsbsim "namespace". I consider anything not explicitely forbidden as being allowed"
• "The sourcecode explicitely takes care of propertynames starting with "/". This shows me, that at least some thoughts have been spent on this topic but they did not resolve into a final solution. Once again: it generally works, just the FDM-reset fails."

Contra

• "I OTOH find it very reasonable to constrain JSBSim components to the /fdm/jsbsim/ subtree. That avoids a lot of potential problems when sharing the property tree with an external application (as is the case in the JSBSim / FlightGear combination). It also works with the present property clean-up scheme."
• "I view touching any property outside /fdm/jsbsim as external communication."
• "IMHO that is a bad idea. But you do as you please, of course."

Options

• "Declare naming of components outside the jsbsim property base as legal. Then there is a bug which should be fixed."
• "Components shall not use names starting with "/" or "../" to be defined outside the jsbsim root. Then this should be documented, a warning/error message been printed or anything alike. And the support for this may be removed from the source."

In fact, this seems to be an issue that is not just specific to FDMs, but more generally it could theoretically affect pretty much any component or subsystem that may be viewed as a single entity at some point:The FDM system in FlightGear is only one of the most modular abstractions using the property tree at the moment, so that the corresponding components (jsbsim and yasim) actually are distinct, and may even run standalone, even as a separate process.

To date, there is no other subsystem in FlightGear that has such a well-defined interface, that it can infact it be exchanged with a different component implementing that interface.

Constraining components (at least by convention) to publish state only in a component-specific subtree seems like the most logical decision, because it encourages and supports the concept of encapsulation, but also illustrates data flow relationships and dependencies (i.e. it would be a safe assumption to make that a component only mutates state that it owns, and that it also internally maintains).

So, doing it this way would also support the notion that components basically 'own' their subtree in the property tree (also see: Lack of ownership concept and access control for properties )and may not mutate outside state without using well defined mechanisms and interfaces (i.e. messages using signals and handlers implemented as listeners).

Generally disallowing write access to 'foreign' properties seems (at the moment) like a bad idea, though - because it would possibly introduce new problems, a better approach might be to provide means for subsystems to register 'ownership' for a certain branch, and then only trace (optionally) write access to such properties that are outside this branch, so that warnings can be issued.

API Requirements

• properly separate the initialization of cockpit controls and core FDM data structures (as discussed in [2])
• allow aircraft to be started and reset/re-initialized at runtime [3]
• allow aircraft FDM configurations and systems to be reloaded from disk at runtime
• allow aircraft to be started "in-flight" using configurable aircraft configurations (such as at a given altitude/airspeed/heading...)
• ensure 100% interoperability between FDMs, so that all FDMs supported by FlightGear can properly clean up and hand over control to another FDM instance, without causing any leftovers such as tied properties, running subsystems etc.
• "it would be nice if the engine were its own subsystem and we could mix-and-match engines and FDMs " [4]

Features

• allow aircraft to query the groundcache in order to provide for realistic ground reactions [5]
• provide proper support for weight & balance modeling (and various fuel tanks)
• provide support to apply arbitrary external forces to aircraft, useful to model winch ops, glider/aircraft towing, pushbacks, water landings catapult starts, sub model impacts, in-flight collisions and emergency chutes (i.e. for spin recovery) - available in JSBSim via FGExternalForces
• allow control surface/aileron characteristics to be modified at runtime (i.e. to model icing)
• provide support to modify the weight of/on surfaces, i.e. also to model icing effects [6]
• provide suport for different types of de-icing equipment modeling
• provide support to use runtime-configurable friction coefficients for runways, for different gear/wheel positions
• provide support to model gear failure by blocking certain landing gear wheels or by allowing wheels to break
• provide support to model water airplanes
• provide support to model tailwheel aircraft

FDM specific features

• provide support to model aerobatic flight

Related discussions

• about fdm properties
• http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg38992.html