Aircraft checklists

Generic Aircraft Checklists

Started in	03/2010
Description	Centralized checklist management
Maintainer(s)	Stuart
Contributor(s)	Stuart Sanhozay
Status	Under active development as of 05/2015
Changelog	/Nasal/checklist.nas /gui/dialogs/checklist.xml /Aircraft/Generic/autochecklist.nas

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 (NOTE: When more than one condition has to be met, the use of <and></and> is mandatory to make this work).
    • <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

FlightGear Aircraft Checklists PUI dialog

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.

Grouping Checklists

Checklists can optionally be grouped together under a <group> node in the property tree, with each group given a descriptive name. For example:

 <group>
  <name>Emergency</name>
  <checklist>...
  <checklist>...
 </group>
 <group>
  <name>Ground</name>
  <checklist>...
  <checklist>...
 </group>

This is supported within the Checklist dialog, and also by the FG1000.

Automatic Tutorial Generation

By default, checklists are automatically converted into tutorials. However, if your aircraft has custom tutorials, or it is not appropriate to have a tutorial for a particular checklist, you can disable this by setting <auto-tutorial>false</auto-tutorial> within the <checklist> or <group>. You can set /sim/checklists/auto-tutorial=false to disable generating any tutorials at all.

Reloading checklists

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

var reload_checklist = func(filename) {
var checklist_path=sprintf("%s/%s",getprop("/sim/aircraft-dir"),filename);
var data = io.read_properties(checklist_path,"/sim/checklists");
}

reload_checklist(filename: "777-200-checklists.xml");

Change the filename to the name of the file you are editing. Make sure to monitor the startup window and/or the Nasal Console loglist widget for any XML related warnings (e.g. parsing errors).

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 does the autostart (see Don't repeat yourself ).

The autochecklist.nas script can be used to create an 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 $FG_ROOT/Docs/README.conditions 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 -->
    </shutdown>
  </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.

Fine tuning checklist bindings

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.

<binding>
  <command>nasal</command>
  <script>
    var auto = getprop("sim/checklists/auto/active");
    if (!auto) gui.showWeightDialog();
  </script>
</binding>

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. Bindings can use the property sim/checklists/auto/expedited to check if the execution is expedited, i.e. there is no wait between items. Note that the expedited flag does not in itself indicate whether a binding is being run as part of an automated checklist. You may need to test both the sim/checklists/auto/active and sim/checklists/auto/expedited properties, e.g.

var auto = getprop("sim/checklists/auto/active");
var expedited = getprop("sim/checklists/auto/expedited");

if (auto and expedited) {
    ...
}

Customizing execution (optional)

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

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 script will not be available. The availability of automated checklists can be tested by checking whether the sim/checklists/auto node is nil and a suitable indication given to the pilot if it is nil.

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

Development

the docs for this particular feature are to be found in $FG_ROOT/Docs/README.checklists. This is also where you can read that the c172p is considered the reference implementation. The system itself is located in $FG_ROOT/gui/dialogs/checklist.xml#l18 (embedded Nasal), but -at least for now- that should not matter to you - unless you want to extend the system to add support for new features (in which case, you'll also want to check out $FG_ROOT/Nasal/checklist.nas). Whatever is added to the Nasal code should never be aircraft-specific - aircraft specific stuff needs to be expressed via your own XML files - if something is missing, just extend the Nasal file, or ask for help so that we can post some pointers/snippets.

it would be a good idea to localie any custom Nasal blocks, and instead introduce custom fgcommands using the addcommand() API - basically the reason being that there could be an aircraft-specific API using fgcommands for starting engines, instead of having aircraft-specific "Nasal blobs" in each checklist file. A while ago, this was actually discussed on the devel list, too. In other words, an "fgcommand" (implemented in Nasal) would help better isolate checklists from aircraft specifics.

Checklist Generation Language

Forum user sanhozay has created a custom language called CLGen for generating checklists.

The main benefits to be gained from using CLGen are:

• More compact Nasal-like syntax that is easier to work with than XML
• Re-use of item definitions means source code is around 20-25% of the equivalent hand-written XML
• PDF and Graphviz DOT views of the checklists to aid prototyping
• Type checking and code generation means less debugging of checklists in Flightgear

Creating checklists with CLGen can be as simple as:

checklist("Startup") {
    check("Parking Brake", "ON");
    check("Navigation Lights", "ON");
    check("Beacon", "OFF");
}

CLGen supports conditions expressed in Nasal-like syntax, bindings, fgcommands, markers and automated inclusion of copyright headers. It is also possible, with some restrictions, to reverse-engineer existing checklists into CLGen source format and to generate PDF and Graphviz DOT representations of existing checklists.

CLGen is written in Java and runs on Mac OS, Linux and Windows platforms with a Java 8 runtime.

For more information, including a step-by-step Wiki tutorial, visit the CLGen project on Github

Related content

Forum topics

• The future of checklists topic on the forum (September 2020)
• Checklist Generation DSL topic on the forum (May 2017) - CLGen Release Announcement

Development mailing list

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