Posted on May 14, 2019 16:09 by haversine

The need for a flexible and scalable way of adding AirFMC support for new planes came from the fact that there are far too many variants and models out there and they are often different but share a common denominator; a set of underlying datarefs. Unfortunately we at Haversine cannot purchase and develop for every single plane that comes out; we try but it’s literally impossible. By releasing a plugin for X-Plane which is configurable, users and plane developers can now attempt to create their own plane files and have them supported even when they are not yet officially. This is achieved with the Haversine Air plugin version 5.0 or above for X-Plane. There is no need to have advanced programming skills just some knowledge of X-Plane and its dataref and command system.

1) The basic principles:
===================

AirFMC is a frontend for plane specific CDUs; it comprises a screen with a finite number of rows and columns and a set of keys which when pressed send a command to X-Plane and act accordingly.

In order to read and display the CDU screen AirFMC through the plugin assumes that its text is stored in string datarefs (1) which can be read. This system therefore only works with planes that expose its MCDU through strings somehow and others who don’t (such as X-Plane itself at the time of writing) can’t be supported.

In other words, the text displayed on the screen must be present and accessible at a memory location in X-Plane.

The second pre-requisite is that the CDU keyboard can be acted upon either through X-Plane datarefs that can be written to, or through commands (2). Writing to each of these variables or commands causes the corresponding key to be pressed.

2) Knowing if the plane what is needed:
================================

We suggest developers to install Datareftool (3) or an equivalent program to inspect X-Plane’s datarefs and see if a) there are text datarefs with the contents of the CDU and b) there are datarefs or commands for each of the CDU keys.

3) The configuration files:
=====================

These are text files with the .hac extension that are present in the HaversineAir folder of the plugin.

The first / basis MUST READ file is named *** default.hac *** and contains all the default as well as a detailed explanation for all fields. Each supported type of plane or CDU requires its own file and is given a unique ID. Planes can inherit behaviour from other variants and therefore can have a parent ID. Most types are therefore children of the default.hac file which has ID 1.

In order to add support for a new plane: from the list of supported planes and configuration files, locate the one that is most similar to the plane/FMC type you’re trying to add support to. Then copy it to a new file with a new name and give it a unique ID above 32768 in order to avoid conflicts.

For example, if you wanted to add support for a new type of Boeing 737 you could copy the file b738-x737fmc.hac to a new file, give it a .hac extension, say b738-myplane.hac, and a new ID say 33000 and set its parent to 1:

Add the following lines:

id:33000
parent_id:1
desc:MY PLANE TYPE

4) Identifying the specific new plane:
==============================

The plugin must be able to detect this new plane and associate it to the new configuration file. This is achieved by a set of identify keywords which identify the plane in question and are unique to it. The most common way to do this is by the plane’s ICAO and TAILNO.

Using Dataref tool look for the datarefs sim/aircraft/view/acf_ICAO and sim/aircraft/view/acf_tailnum and note down their values. Then add two lines to the config file (or replace) such as:

identify:icao:noted-icao
identify:tailno:noted-tailno

From then on, whenever the plugin launches, when it detects these two unique values it will consider this file to be its appropriate one.

5) Configuring FMC defaults:
========================

You can perform a few generic configuration tasks by adding or modifying lines such as:

fmc:colour:grey
fmc:nocols:24
fmc:norows:14
fmc:dualfmc:0
fmc:type:default

Namely, the you’ll be able to change the number of columns of the CDU to a higher one if it has more than the default which is 25.

Refer to the default.hac file for a description of available commands and their format.

6) Configuring the keyboard:
========================

AirFMC comprises 6 left and 6 right LSKs, a digit pad with 12 circular keys, an alpha pad with 30 keys and a control pad with 5+6+2+2 keys. Create a line (or adjust or copy-paste) for each of these keys (refer to default.hac). For each key you’ll need to enter the dataref or command which actuates on it (note them down or copy-paste from Dtaref tool). You’ll also need to specify the type of dataref or command.

For example the line:

fmc:key:11:LK1:float:FJCC/UFMC_1/LK1

indicates that the dataref of type *float* and name *FJCC/UFMC_1/LK1* acts on the left LSK.

If the key is a command instead of a datyaref, use the cmd keyword, for example:

fmc:key:65:A:cmd:laminar/B738/button/fmc1_A:laminar/B738/button/fmc2_A

The number following key identifies the key itself and must be one of:

11 to 16 for left LSKs
21 to 26 for right LSKs
49 to 60 for digit pad keys
65 to 94 for alpha keys
130-134, 140-145, 150-151 and 160-161 for control keys

7) Configuring the CDU screen:
=========================

Similarly, for each of the N lines (default are 14) of the CDU, specify which datarefs to read from. For example, from b738-x737.hac:

fmc:line:1:0xffffffff:0::FJCC/UFMC/LINE_1
fmc:line:2:0xffffffff:0::FJCC/UFMC/LINE_2
fmc:line:3:0xffffffff:0::FJCC/UFMC/LINE_3
fmc:line:4:0xffffffff:0::FJCC/UFMC/LINE_4
fmc:line:5:0xffffffff:0::FJCC/UFMC/LINE_5
fmc:line:6:0xffffffff:0::FJCC/UFMC/LINE_6
fmc:line:7:0xffffffff:0::FJCC/UFMC/LINE_7
fmc:line:8:0xffffffff:0::FJCC/UFMC/LINE_8
fmc:line:9:0xffffffff:0::FJCC/UFMC/LINE_9
fmc:line:10:0xffffffff:0::FJCC/UFMC/LINE_10
fmc:line:11:0xffffffff:0::FJCC/UFMC/LINE_11
fmc:line:12:0xffffffff:0::FJCC/UFMC/LINE_12
fmc:line:13:0xffffffff:0::FJCC/UFMC/LINE_13
fmc:line:14:0xffffffff:0::FJCC/UFMC/LINE_14

The 0xffffffff is the colour in which this line is to be displayed in RGBA, meaning white, and the following 0 is the font size (0 being the default). It is possible to have one line represented by several datarefs each with its own colour and font size combination. There are also advanced line parsing techniques such as from right to left which are described in the default.hac file although the standard is from left to right.

8) Annunciators:
==============

It is also possible (although not mandatory or required) to specify annunciator datarefs for the EXEC button light and the lights / words that appear on the side of the FMC. See the annunciator configuration options in default.hac for more details on these.

9) Try and adjust:
==============
That’s it; launch X-Plane and the plugin and see if it detects the new configuration file. Go back to the file and adjust lines and datarefs as needed.

10) Contributing with your file:
==========================

Especially for plane developers, if you’ve made your plane work with AirFMC by creating a config file for it and would like for it to be distributed with the next plugin version as well as for it to be mentioned on the list of supported planes, please contact us via support and we’ll be only too happy to add it to the list of officially supported planes and CDU types.

11) Help / Contacting us:
====================

Use the contact / support form to get in touch and Haversine will be glad to get back to you by email and help in creating a new config file.

12) References:
============

(1) http://www.xsquawkbox.net/xpsdk/mediawiki/Category:XPLMDataAccess
(2) https://developer.x-plane.com/sdk/XPLMUtilities/
(3) https://forums.x-plane.org/index.php?/forums/topic/82960-datareftool-is-an-improved-datarefeditor-open-source-better-search-change-detection/