Aircraft checklists

The Aircraft Checklists dialog

As of version 2.9, FlightGear can display aircraft checklists in a standardized way, under Help > Aircraft Checklists.

Adding checklists

To learn more about creating custom checklists, see $FG_ROOT/Docs/README.checklists and the Cessna 172P as the reference implementation. Increasingly, the tutorials system is also extended such that it may make use of aircraft checklists.

Checklists are situated under /sim/checklists. As the checklists may be quite long, it is recommended that they are put in a separate file using the following entry in the -set.xml file of the aircraft:

<checklists include="c172-checklists.xml"/>

Each individual checklist is created under a <checklist> XML tag, with the following sub-properties:

• <title> The name of the checklist
• <page> One or more pages from the checklist, containing one or more of the following:
  • <item> A checklist item, containing
    • <name> The item name, to appear on the left hand side of the checklist
    • <value> One or more values, to appear on the right hand side of the checklist. Second and and subsequent <value> tags are displayed underneath each other. It is recommended that the <value> tags are kept short, to minimize the size of the displayed checklist.
    • <condition> An optional condition node that evaluates when the checklist item is complete. Incomplete checklist items are shown in yellow, while completed items are shown in green.
    • <marker> An optional marker node that is used to display a circle around a control when the user clicks a "?" button next to the item. This contains <x-m>, <y-m>, <z-m> and <scale> sub-elements and uses the tutorial marker. Note that this requires the marker model to be included in the aircraft model, as explained in the aforementioned article.
    • <binding> Zero or more XML bindings that are used by the simulator to execute the checklist item if the user clicks on a ">" button next to the item.

For simple checklists the <page> element can be omitted and <item> entries placed directly under the <checklist>.

The following example shows a simple checklists XML file:

 <PropertyList>
  <checklist>
    <title>After Landing</title>  
    <item>
      <name>Carburetor Heat</name>
      <value>COLD</value>
      <condition>
        <equals>
          <property>/controls/anti-ice/engine[0]/carb-heat</property>
          <value>0</value>
        </equals>
      </condition>
      <marker>
        <x-m>-0.3225</x-m>
        <y-m>-0.0850</y-m>
        <z-m>-0.2117</z-m>
        <scale>2.0500</scale>
      </marker>      
      <binding>
        <command>property-assign</command>
        <value>0</value>
      </binding>
    </item>
    <item>
      <name>Wing Flaps</name>
      <value>UP</value>
    </item>
  </checklist>
  <checklist>
    <title>Getting hamburger</title>
    <page>
      <item>
    ...
      </item>
    </page>
  </checklist>
 </PropertyList>

See the Cessna 172P for an example of how this all fits together.

Bindings

One or more binding elements can be added to a checklist item. Conceptually, these are the actions that the user should execute to complete the item. The checklist GUI displays items with such <binding> elements with an additional [>] button. Clicking on the button executes the bindings, allowing the user to watch as the computer/co-pilot/instructor executes the checklist item.

The <binding> element is exactly as you would expect - so property-assign, nasal etc. works.

The plan is to extend this function so that checklists with one or more items containing a <binding> element can have an (optional) button to execute the entire checklist.

Reloading checklists

Cut and paste this little code snippet in the Nasal console and excecute it:

var checklist="777-200-checklists.xml";
var checklist_path=sprintf("%s/%s",getprop("/sim/aircraft-dir"),checklist);
var data = io.read_properties(checklist_path,"/sim/checklists");

Change the first variable to the name of the file you are editing.

Automated checklist execution

Work in progress This article or section will be worked on in the upcoming hours or days. See history for the latest developments.

As of version 3.5, FlightGear can automate the execution of various sequences of aircraft checklists using the autochecklist.nas script in $FGDATA/Aircraft/Generic. This can be used to an create autostart menu but is not restricted to autostart; any checklist sequence can be run from any piece of Nasal code.

The advantage of this approach is that the checklist files become the source of checklists, tutorials and autostart. If the checklists change, so do the tutorials and autostart.

Automated checklists may not work for more complex aircraft startup sequences, but they are so easy to set up that it's worth trying alongside the development of the aircraft startup process. If it works, great! If it doesn't, you haven't wasted your time because you have made a start on your checklists.

Background

The script relies on the aircraft having a set of checklists that have complete sets of bindings to take the aircraft from one state to another. For autostart, for example, you need to be able to start the aircraft solely by pressing the binding buttons on the right side of the checklist.

To use the script, define a named sequence of checklists to be run on demand. For example, you could define a sequence called "startup" that runs the sequence of checklists: "Before Starting Engines" and "Start Engines". You could also define a sequence of checklists called "shutdown" that runs a sequence containing a single checklist "Parking and Secure".

When you invoke the autochecklist script, it executes the checklists defined in the sequence in the order that they are listed. Starting with the first item in the first checklist, it checks the condition associated with the checklist item. If false, it runs the binding. It then moves onto the next item and checks if the condition from the previous item has been satisfied. If not it waits for a number of seconds (maybe the binding was interpolated or the condition is waiting for something to start, e.g. APU spooling up). Once the condition from the previous item is satisfied, it looks at the condition on the current item and runs the binding if the condition is false. Execution continues like this until all checklist items have their bindings satisfied.

In some cases, e.g. checks on maximum takeoff weight, bindings will never cause the condition to be satisfied. To cover these cases, the script will consider the checklist to have failed if the condition associated with a checklist item does not become true within a timeout period. In these cases, the pilot needs to review the checklist manually and work out why the aircraft will not start. Once the condition has been corrected, e.g. they removed some fuel or payload to get below MTOW, the checklists can be executed again and should be successful. Because the script checks the condition of each item before running the binding, the automated execution is re-entrant; it just picks up where it left off and does only what needs to be done.

Add the script

Add autochecklist.nas to the aircraft's -set.xml file (or equivalent):

<nasal>
  <!-- Other scripts here ... -->
  <autochecklist>
    <file>Aircraft/Generic/autochecklist.nas</file>
  </autochecklist>
</nasal>

Define checklist sequences

In the aircraft's -set.xml file, create one or more named checklist sequences that specify ordered lists of checklists to execute.

For example, to run checklists with indexes 0 and 1 for startup and checklist 9 for shutdown:

<checklists>
  <checklist include="Checklists/before-starting-engines.xml"/>
  <checklist include="Checklists/start-engines.xml"/>
  <!-- Other checklists here ... -->
  <checklist include="Checklists/parking.xml"/>
  <startup>
    <index n="0">0</index> <!-- Before starting engines -->
    <index n="1">1</index> <!-- Start engines -->
  </startup>
  <shutdown>
    <index n="0">9</index> <!-- Parking -->
  </startup>
</checklists>

Execute the checklist sequence

For the typical usage of autostart, add a Nasal binding as a menu item and execute the named checklist sequence:

<item>
  <label>Autostart</label>
  <binding>
    <command>nasal</command>
    <script>autochecklist.complete_checklists("startup");</script>
  </binding>
</item>

Obviously, additional logic can be included in the binding if you want the autostart menu to toggle between autostart and shutdown.

Expedited checklists

For in-air start sequences, you can pass zero as the second argument of the complete_checklists function to expedite the sequence. All items in the checklist sequence will be executed without waiting for previous items to complete. This may not be suitable for aircraft that need to wait for something to happen before being able to start engines. Note that this means the checklist sequence can never be considered to have failed.

if (!getprop("gear/gear/wow")) {
    autochecklist.complete_checklists(sequence: "in-air-start", wait: 0);
} else {
    autochecklist.complete_checklists("ground-start");
}

Clearly the checklist sequence used for in-air start should be different from a ground start and should put the aircraft into a flying state, e.g. gear up, flaps up.

Customizing execution (optional)

The autochecklist script can be customized by setting properties, either in the aircraft -set.xml file or at runtime:

<checklists>
  <auto>
    <completed-message>Checklists complete.</completed-message>
    <startup-message>Running checklists, please wait ...</startup-message>
    <timeout-message>Some checks failed.</timeout-message>
    <timeout-sec>10</timeout-sec>
    <wait-sec>3</wait-sec>
  <auto>
</checklists>

• completed-message message displayed on successful completion of the checklist
• startup-message message displayed prior to automated checklist execution
• timeout-message message displayed if checklist execution times out waiting for a checklist condition to be satisfied
• timeout-sec if the previous condition is not satisfied within this timeout, the automated execution fails
• wait-sec time to wait before re-checking the status of the previous item if its condition is false after running the binding

Messages are displayed as copilot announcements (by setting sim/messages/copilot). They can be empty if messages are not required. Note that messages are not displayed for expedited starts.

Other features and ideas

Sometimes, a checklist binding will do something like display a dialog, e.g. fuel and payload dialog. It would be irritating to the pilot if these things happened during automated execution. These bindings can make use of the sim/checklists/auto/active property, which will be true (1) when the checklist binding is being run by the autochecklist script and false (0) otherwise.

Automated checklist execution is not restricted to autostart and shutdown. If you have an "After Landing" checklist that switches landing lights off, raises flaps and turns taxi lights on, for example, you could assign that to a keyboard shortcut. Rollout and taxi is a busy time on some aircraft and it's often not easy to find the switches and controls necessary to complete this kind of checklist.

For an example of using automated checklists, refer to the Lockheed Constellation, for which the script was originally written. Note that you need a recent clone of FGDATA, otherwise the autochecklist.nas script will not be available.

External link

• Aircraft Checklists (mailing list)
• Automated Checklist Execution (mailing list)