flightgear/docs-mini/README.electrical

Specifying and Configuring and Aircraft Electrical System
=========================================================

Written by Curtis L. Olson <http://www.flightgear.org/~curt>

February 3, 2003 - Initial revision.
June 14, 2005 - Important update

UPDATE - June 14, 2005
======================

The xml data driven electrical system described in this document has
severe flaws and is (or should be) obsolete.  It is still supported
for backwards compatibility, but new electrical systems should not be
modeled with this system.  Instead you should make a procedural
electrical system model using nasal, or wait for a better data driven
electrical system model to be developed "some time" in the future.

Currently the old/depricated electrical system has been made into a
proper subsystem.  Most aircraft will load the default "systems"
configuration via the "/sim/systems/path" property which is set in the
top level preferences.xml file and which defaults to a value of
"Aircraft/Generic/generic-systems.xml".  The generic-systems.xml file
in turn specifies an electrical system based on the old/obsolete
system.  The default electrical system configuration file named in
"generic-systems.xml" is "generic-electrical.xml".  This mechanism
provides a generic electrical system to any aircraft that doesn't
define their own electrical system.  Also note that you can still
specify a path to an "old" xml config file using
"/sim/systems/electrical" in your aircraft-set.xml file.  This is
again for backwards compatibility.



What follows here is a description of the "old" "depricated"
"obsolete" electrical system.



Introduction
============

The FlightGear electrical system model is a simplification of reality.
We don't model down to the level of individual electrons, but we do
try to model a rich enough subset of components so that a realistic
electrical system may be implemented (at least from the pilot's
perspective.)  We try to model enough of the general flow so that
typical electrical system failures can be implimented and so that the
pilot can practice realistic troubleshooting techniques and learn the
basic structure and relationships of the real aircraft electrical
system.

The FlightGear electrical system is essentially a directed graph built
of 4 major components: suppliers, buses, outputs, and connectors.
Suppliers are the power sources such as batteries and alternators.
Buses collect input from multiple suppliers and feed multiple outputs.
Outputs are not strictly necessary, but are included so we can assign
current draws, and name generic output types, as well as provide a
consistent naming scheme to other FlightGear subsystems.  Finally
connectors connect a supplier to a bus, or a bus to an output, and
optionally can specify a switch property (either a physical switch or
a circuit breaker.)

At run time, FlightGear parses the electrical system config file and
builds a directed graph (in the computer science sense.).  Each time
step, the current is propagated forward through the system, starting
at the suppliers, flowing through the buses, and finally to the
outputs.  The system follows the path specified by connectors and
honors the state of any connector switches.

FlightGear uses a depth first recursive decent algorithm to propagate
the current through the system.  As the recursive calls complete, the
current draw of the "leaf nodes" can be summed up and back-propagated
through the system.  This allows us to compute the total downstream
current draw at each component of the system.  This allows us to
discharge the battery based on actual loads, and allows us to build an
accurate functioning ammeter model.


Suppliers
=========

A supplier entry could look like the following:

  <supplier>
    <name>Battery 1</name>
    <prop>/systems/electrical/suppliers/battery[0]</prop>
    <kind>battery</kind>
    <volts>24</volts>
    <amps>60</amps>   <!-- WAG -->
  </supplier>

<name> can be anything you choose to call this entry.
<prop> is the name of a property that will be updated with the state
       of this supplier.
<kind> can be "battery", "alternator", or "external".
<volts> specifies the volts of the source
<amps> specifies the amps of the source

Currently <volts> and <amps> are not really modeled in detail.  This
is more of a place holder for the future.

For alternators, you must additionally specify:

    <rpm-source>/engines/engine[0]/rpm</rpm-source>

The value of the rpm source determines if the generator is able to
produce power or not.


Buses
=====

A bus entry could look like the following:

  <bus>
    <name>Essential/Cross Feed Bus</name>
    <prop>/systems/electrical/outputs/bus-essential</prop>
    <prop>/systems/electrical/outputs/annunciators</prop>
    <prop>/systems/electrical/outputs/master-switch</prop>
  </bus>

<name> is whatever you choose to call this bus

You can have an arbitrary number of <prop> entries.  Each entry is the
name of a property that will be updated with the value of the current
at that bus.  This allows you to wire devices directly to the bus but
does not allow you to insert a switch or circuit breaker in between.
See "Outputs" and "Connectors" if you want to do that.


Outputs
=======

An output entry could look like the following:

  <output>
    <name>Starter 1 Power</name>
    <prop>/systems/electrical/outputs/starter[0]</prop>
  </output>

An output isn't entirely unlike a bus, but it's nice conceptually to
have a separate entity type.  This enables us to specify a common set
of output property names so that other subsystems can automatically
work with any electrical system that follows the same conventions.  An
output lives on the other side of a switch, so this is how you can
wire in cockpit switches to model things like fuel pump power,
avionics master switch, or any other switch on the panel.

<name> is whatever you choose to call this bus

You can have an arbitrary number of <prop> entries.  Each entry is the
name of a property that will be updated with the value of the current
at that bus.  This allows you to wire devices directly to the bus but
does not allow you to insert a switch or circuit breaker in between.
See "Outputs" and "Connectors" if you want to do that.

Other FlightGear subsystems can monitor the property name associated
with the various outputs to decide how to render an instrument,
whether to run the fuel pump, whether to spin a gyro, or any other
subsystem that cares about electrical power.


Connectors
==========

An connector entry could look like the following:

  <connector>
    <input>Alternator 1</input>
    <output>Virtual Bus 1</output>
    <switch>/controls/switches/master-alt</switch>
    <initial-state>off</initial-state>  <!-- optional tag -->
  </connector>

A connector specifies and input, and output, and any number of
switches that are wired in series.  In other words, all switches need
to be true/on in order for current to get from the input to the output
of the connector.

<input> specifies the <name> of the input.  Typically you would
specify a "supplier" or a "bus".

<output> specifies the <name> of the output.  Typically you would
specify a bus or an output.

You can have an arbitrary number of <switch> entries.  The switches
are wired in series so all of them need to be on (i.e. true) in order
for current to pass to the output.

Note: by default the system forces any listed switches to be true.
The assumption is that not every aircraft or cockpit may impliment
every available switch, so rather than having systems be switched off,
with no way to turn them on, we default to switched on.

This is a problem however with the starter switch which we want to be
initialized to "off".  To solve this problem you can specify
<initial-state>off</initial-state> or
<initial-state>on</initial-state> Switches default to on, so you
really only need to specify this tag if you want the connector's
switch to default to off.


Summary
=======

The electrical system has a lot of power and flexibility to model a
variety of electrical systems.  However, it is hopelessly flawed and
cannot model a lot of more complex electrical behavior needed for the
advanced electrical systems found on larger and more complex aircraft.
Please consider writing a procedural model for your electrical system
in nasal or wait for a better data driven electrical system model to
be developed.  If you know something about electrical systems, please
volunteer to write a better data driven model! :-)