MCDU Programming

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

Subsystem Modes

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

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.

Broker Keys

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.

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

MCDU Commands

Mode Selection

{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

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.

{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

{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

Mode Changes

Key Presses

MCDU Keystroke Codes

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.