MCDU Programming

Hoppie Home

747-400 MCDU

Last updated on 19-Aug-2010 16:21Z

The main interface to the MCDU from a program point of view is through the Broker. This means asynchronous communications over a TCP socket. From version 2.4 on, the MCDU also has a local socket server, so that it can operate completely independently from the Broker (and thus, from PS1). You lose the multiple-MCDU-on-one-bus option, though.

If you fill in off in the Broker IP field on the Config page, the MCDU won't have TCP connectivity and is pretty useless. If you fill in an IP address (or DNS host name), the MCDU will try to establish communication with a Broker at that address. If you fill in server, the MCDU will start a local socket server on port 0x747 (1863 decimal). You can send all commands listed below directly (even without the curly braces) to this socket.

If you postfix a slash and a port number to any entry (except off) in the Broker IP field, such as server/1234, the MCDU will use the given port and not the default 0x747 (1863 decimal).


Subsystem Management

Although the MCDU does quite some management things itself, the connected applications should adhere to a few rules in order to cooperate properly.

Subsystem Modes

The most important issue is mode awareness. Each MCDU on the bus (Broker) always is in a particular mode, and only applications that address this mode will control the MCDU. This is done so that if you hook up more than one MCDU, they can each control a different subsystem. If two MCDUs are in the same mode, their screens will synchronise to ease life for submodule programmers (who otherwise would have to make all their code re-entrant). Note: when using the local socket server, multiple MCDUs are not supported (but multiple modules on one MCDU will work).

At submodule registration time, the module name of the module is passed to all MCDUs and this name appears on their MENU pages. Only a manual selection from the MENU page can change the mode of an MCDU. Outgoing events from the MCDU carry this mode, and incoming commands for the MCDU are filtered for the mode. Applications may register some function keys to also force a mode change (modkey).

MCDU Resets and Registration

One of the modes that a subsystem may receive is "reset". This is a generic notification that the MCDU has reset itself, either by a power cycle or by explicit user action. An MCDU reset causes the MCDU to drop all registered submodules. Therefore each module should re-register shortly after receiving the reset message.

Broker registration in general should be a four-step process.

  1. When you first connect to the Broker, you should do a Broker registration to properly list your program in the Broker. This has nothing to do with the MCDU.
  2. After this, subscribe to the mcdu.event key to receive MCDU events. Usually you want to set up an event handler in your program to handle these asynchronous messages. Polling them is usually not such a good idea.
  3. Then register with the MCDU by writing to the mcdu.cmd key, using the modadd modName command.
  4. Lastly, see whether you get confirmation of your registration via a MCDU event telling you modadded modName. If not, you may assume the MCDU is not available at this time. Typically your application should retry to register every 30 seconds or so. Trick: as the Broker won't pass on your repetitive re-registration attempts (as the key value does not change!), append a random string to your modadd modName command.
When you use the direct socket link, you can skip the registration and notification steps, but you should send the modadd command and follow all other tips. Only the Broker handling does not apply.


Broker Keys

Two Broker keys carry all traffic between the MCDU and the connected application programs.
  1. mcdu.cmd: all MCDU commands must be written to this key. Commands to the MCDU are divided into several categories, mostly related to Display Control.

  2. mcdu.event: the MCDU writes to this key if an event takes place, such as a function key press.

All MCDU applications need to subscribe to the mcdu.event key for notifications about possibly interesting events, and need to write to the mcdu.cmd key in case they want the MCDU to do something.

Again, you can skip all this if you use the direct socket link.


MCDU Commands

A command can be sent to the MCDU as a string that is written to the mcdu.cmd Broker key. The generic string format consists of a command word followed by several data words. If data words contain spaces, you need to brace the word with braces or double quotes. For example, {display fmc 2 0 {<ECON SPD}} would ask the MCDU(s) in FMC mode to display the ECON SPD prompt on data line L1. The braces around the whole sentence are needed to protect the spaces in the command line (not needed when using the direct socket link).

Mode Selection

{modadd modName}
{modremove modName}
: register and de-register an external program as a submodule of the MCDU. The modName appears on the MCDU MENU page as a selectable item. Duplicate menu entries are silently ignored. There are no command provisions to determine where on the MENU page the entry will appear, but the MCDU Menu Layout page allows you to influence it. Maximum number of visible entries is eleven, sorted alphabetically (or as determined by Menu Layout). Only the first eight characters of the module name will be displayed, but the full given name is significant for selections.

{modkey modName {keySym keySym keySym...}}: Assigns function keys to the module. The module must already exist in the system (use modadd). After a function key has been added, pushing this function key from within any MCDU mode will call up the given module. They pushed key will be made available to the module by putting the keysym in the second part of the keypress event (see Key Presses below).

If two modules both claim the same function key(s), the last module that registers, wins. Dual registration is by design not supported.

Display Control

In principle, the MCDU only accepts uppercase characters that have a direct mapping to the MCDU character set (visible on one of the test pages). Lowercase input will be converted to upper case.

An exception is made for various characters which do not have a natural mapping to a standard ASCII character, but which are part of the ARINC 739 standard. Some of these such as the degree symbol ° are used in many places, others such as the up and down arrows typically only appear in FANS implementations.

MCDUInput
Degree'
Box!
Arrow Up^
Arrow Down?
Arrow Left:
Arrow Right;
Triangle~

{clear modName {page title}}: if in modName mode, clears the complete MCDU screen except the scratch pad, and displays the page title as given (always centered and in large font). If you do not want a page title, you may leave the second field out (and redraw manually using the display command).

Notice: if you change the screen layout in rows and columns using the configuration files, of course the display command limits change.

{display modName row col {screen line} font}: sends strings to display to the MCDU(s) in modName mode. The MCDU contains a page title (row 0), six pairs of title/data rows (1+2, 3+4, ..., 11+12), and a scratch pad (row 13, which should not be written to by this command but by the scratch command instead). Each row has 24 colums, column 0 is the leftmost. All lines can display text in both small and large font, using these keywords. It depends on the line which font is the default. Negative rows and columns are allowed, -1 is the bottom row or the rightmost column. Special column signs: "l" aligns text left, "c" centers text, "r" aligns text right. You can see which characters are accepted for display by watching the test patterns. All fields above are required, except for the font field. More than 24 characters on a line will be ignored.

{colour colour}: Sets the MCDU colour to colour. All ARINC 739A-1 colours are available: black, cyan, red, yellow, green, magenta, amber, and white. Subsequent display commands will draw in this colour. If your leave the colour parameter off, the MCDU switches back to the default colour from the display mode config file. clear and scratch always revert to the default colour.

{displayc modName row col colour {screen line} font}: A very close relative to display, but with a colour parameter inside so you do not need to use the separate colour command. The effect is exactly like using colour followed by display. If you explicitly want to revert to the default colour, use "" as colour.

{scratch modName {new content}}: this command replaces the current scratch pad content with the new content on all MCDUs in modName mode. This should not be used for messages, but only for "downselect" operations. If a message is currently on display, the new content is buffered and will appear as soon as all messages have been cleared.

{msgadd modName {message text}}
{msgremove modName {message text}}: enters a new message in the MCDU message queue(s), or removes one. A new message illuminates the MSG annunciator, is displayed in the scratch pad, and blocks the MCDU until the user presses CLR or the message is removed by the msgremove command. If the message is on display when it is removed, it disappears. If it was already cleared by the user, the msgremove command is ignored. The scratch pad is saved while a message covers it, and will reappear after the message is removed. If there is more than one message in the queue, each message will appear in order of submission to the MCDU when the previous message is removed. The special module name all causes the message to (dis)appear on/from all connected MCDUs, and should be used with caution.

Various

{ann modName type state}: controls the state of the annunciators. Five annunciator types are recognised: dspy, exec, fail, msg, and ofst. The state can be 0 for off and 1 for illuminated. Not all hardware supports all types of annunciators. For the moment, the MCDU does not remember the annunciator state when switching out of a mode, but it always switches all annunciators off while entering a new mode.

{keyboard mapName}: remotely switches the keyboard map of the MCDU. Note that this does not change the persistant keyboard map, this can only be changed by the configuration page. The keyboard command is mainly useful if you want to remotely switch the MCDU keyboard (not the mouse) off for a while. Recognised maps are PS1, PFC, and off.

{key MCDU_ID keyName counter}: sends a keystroke to a specific MCDU. Unlike all other commands, this one does not require a mode parameter, but a MCDU identifier to single out one specific MCDU. You can set this ID on the MCDU Config page; I suggest one of (left, center, right). This will vary between installations, so keep it configurable! The keyName is a keystroke name out of the table below. counter is just a changing parameter to keep the Broker from stopping repeated key strokes, I suggest a simple wraparound counter from 0 to 99.

{passthrough modName}: puts the addressed mode in the passthrough state. This means that all non-function keys, alpha and numeric, CLR, DEL and so on will immediately be sent to the subsystem. The scratch pad editor is not provided any longer by the MCDU, you need to do it all by yourself.


MCDU Event Monitoring

All things happening to the MCDU can be monitored by changes in the mcdu.event Broker key. As with the command key, events are identified by a word, and may carry parameters separated by a space. If parameters contain spaces, they might be braced by braces.

Mode Changes

{modadded modName}
{modremoved modName}: indicates that a new subsystem has just been added to or removed from the MCDU. This is mainly used for backreporting to the new subsystem, as an indication of successful (de)registration. Other subsystems may track this event to get notified of the new subsystem, too.

Key Presses

{key modName keyName {scratch pad} counter}: this event triggers for every functional key pressed. Functional keys are keys that should be intercepted by the application, such as LSKs and the Next Page/Prev Page keys. Alphanumerical and special (DEL/CLR) keys stay within the MCDU and only manipulate the scratch pad. The internal config mode does not send keystrokes out, so you cannot use it to test. The many dedicated FMC keys, such as INIT REF, also don't sent out keystrokes. You can register an application for these keys using the modkey command.
The value of this event consists of four parts. The first part is the module name, so that only the correct subsystem will react. Note that the special module name reset should be reacted on by all subsystems.
The second part is the pushed key in mnemonic form, coming from the keystroke list below. menu means that the MCDU main menu has been used to select the module, and the module menu should be displayed.
The third part is the current content of the scratch pad. This is always in lowercase letters, except for the single occurrence of "DELETE" when the DEL key has been pressed.
The fourth part is a simple counter, which can be ignored by all applications. It is used to make the transmission of multiple equal key presses through the Broker possible.


MCDU Keystroke Codes

This table contains all keystrokes that the MCDU recognises. Some of these are also sent out. See the documentation of the key command and the key event for details.

KeycodeSent
clr 
exec 
sp 
prevpageyes
nextpageyes
navrad 
menu 
del 
0 
1 
2 
3 
4 
5 
6 
7 
8 
9 
a 
b 
c 
d 
e 
f 
g 
h 
i 
j 
k 
l 
m 
n 
o 
p 
q 
r 
s 
t 
u 
v 
w 
x 
y 
z 
prog 
initref 
rte 
deparr 
atc 
vnav 
fix 
legs 
hold 
fmccomm 
lsk1lyes
lsk2lyes
lsk3lyes
lsk4lyes
lsk5lyes
lsk6lyes
lsk1ryes
lsk2ryes
lsk3ryes
lsk4ryes
lsk5ryes
lsk6ryes
+/- 
. 
/ 


Hints and Tips

  • Take care that you usually need to check for five things when processing an LSK push. 1. Reset mode? If so, re-register. 2. Correct mode? If not, ignore. 3. Scratch pad empty? Downselect! 4. Scratch pad "DELETE"? Delete! 5. Otherwise upselect.
  • For debugging and tests, consider to use the plain TELNET program that always comes with your operating system. Connect it to the Broker or directly to the MCDU (in server mode) and type away.


© 2019 Jeroen Hoppenbrouwers For more information, mail to hoppie@hoppie.nl