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

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

The autochecklist.nas script 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.

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 at least made a start on your checklists.

Background

The autochecklist.nas 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.

Using the script is a simple three step process involving a few lines of XML and as little as one line of Nasal code:

1. Add the script to your aircraft
2. Define one or more named checklist sequences
3. Call the script to execute a checklist sequence

For example, you could define a sequence called "startup" that runs the sequence of checklists: "Before Starting Engines" and "Start Engines". Calling the autochecklist.nas script from a menu item binding with "startup" as the argument creates an autostart menu.

When you invoke the autochecklist script, it executes the checklists defined in the named 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 it is still false, 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>
  ...
  <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. The names can be anything you like as long as they are valid XML tags. The names are never displayed within the simulator.

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

<sim>
  <checklists>
    <checklist include="Checklists/before-starting-engines.xml"/>
    <checklist include="Checklists/start-engines.xml"/>
    <!-- Other checklists here with indexes 2 to 8 ... -->
    <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>
</sim>

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 in some aircraft, 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. Note that this means the checklist sequence is never 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's -set.xml file or at runtime. Configuration is under the sim/checklists/auto node.

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

• startup-message message displayed prior to automated checklist execution
• completed-message message displayed on successful completion of the checklist
• 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 (effectively a polling interval).

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

Care should be taken with the timeout value. This is the timeout for a single item waiting for the previous condition to be satisfied, not the overall timeout for the checklist sequence. If the timeout is set to a large value and conditions cannot be satisfied, the pilot will have to wait a long time for the failure message to appear.

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 when the checklist binding is being run by the autochecklist script and false 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.

To use the autochecklist.nas script, pilots need FGDATA v3.5 or greater, otherwise the autochecklist.nas script will not be available. The availability of the autochecklist script can be tested by checking whether the sim/checklists/auto node is nil and a suitable indication given to the pilot.

For an example of using automated checklists, refer to the Lockheed Constellation, for which the script was originally written.

External link

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