PSX Network Protocol

The PSX Network Protocol

PSX exchanges messages with all clients (including the Router) using a simple, line-based, readable ASCII protocol. This means that nearly all programming languages in use can easily talk to PSX, and it is well possible to use a typing command line interface to monitor and interact with PSX.

This tutorial assumes that your add-on program, or your manual command line interface, has been set up and connected to PSX (server or router). This procedure is described in the PSX Connection Protocol.

To describe protocol message exchanges, this tutorial uses the following notational conventions:

string

A one-line message string being received from PSX. Remember: coming from a network stream, appearing to you as input.

> string

A one-line message string being sent to PSX. Remember: from you as output, going into a network stream. You may view the > symbol as a prompt on a command line, though the actual symbol will not be present either on the command line or in the network stream.

Protocol Example

----- connection established -----
id=0
version=10Alpha25b
> name=Captain's Displays
Qh54=887
> Qh87=332
Qi54=889
Qs5=<econ            select>
Qh712=8192
> exit
----- connection closed -----


You see that the server gives you a connection ID (0) and its current version (10Alpha25b). You then upgrade the connection ID to a client name (Captain's Displays). This name upgrade is just so that the server end may show a more meaningful name than just 0 in certain lists. It is never actively used to make decisions by machines.

The next exchange of Q variables is what the bulk of a PSX network connection is about. You receive a variable from PSX (code h54, value 887), then send a variable to PSX, receive three back, etc.

Lastly, you send "exit" to PSX and the connection is broken.

It is important to implement this message exchange in such a way that your add-on program can react to incoming messages all the time, irrespective of when they arrive, or in which order. This means that you must implement some form of event handler for incoming messages. It will never work if you expect certain strings and block your program until they arrive. This mode of operation is called asynchronous or non-blocking and most programming languages support it. You can make good use of the protocol that all messages are ended by a CR/LF byte sequence. Many programming languages allow you to set up the TCP connection in line buffering mode so that your add-on program is only notified of a complete message arrival, not the individual bytes.

If you can set a buffer size, you should not go over the top. Typical PSX messages have a maximum length of about 60 bytes, and an average length of about 12. As long as your add-on program can handle them fast enough, you do not need to provide much more than a few Kb worth of buffering.

Concerning whitespace: you should never include excess white space in the protocol, and neither should you remove whitespace. Especially leading and trailing spaces in the Qs variable messages are significant. More information about this is available in the section about the Qs variable category.

PSX Variable Categories

This documentation is not authoritative. The official PSX documentation on the Aerowinx web site always takes precedence.

PSX distinguishes three main variable categories: Qh, Qi, and Qs.

Qh: "human"

These variables are linked to mechanical objects on the flight deck that can be operated by humans. Switches, levers, knobs, etc., are all linked to a Qh variable. If you operate anything on the flight deck, you should send a Qh variable to PSX. Likewise, if the PSX Server notices that something was operated, it will send a Qh variable to you. You do not get your own Qh variables back.
All Qh variables are plain integers.

Qi: "internal"

PSX has many internal variables that keep track of the state of the Big Machine. These Qi variables contain elementary data such as position, altitude, airspeed, and many other aspects of the running simulation. Unlike the Qh variables, you cannot change Qi variables directly. You cannot override the running simulation. You must change inputs to the simulation, usually by the Qh variables, and hope the effect you desire actually happens. For example, you cannot force the landing gear down using the Qi for the landing gear state; you must ask the simulator to lower the landing gear, using the Qh for the gear lever. The sim will move the lever and, if aircraft conditions allow it, the lever will command the internal landing gear hydraulics accordingly.
Indicators on the flight deck are usually Qi. You cannot make a light blink just by setting its Qi var; you must make the Big Machine decide it is time to blink the light.
All Qi variables are plain integers.

Qs: "string"

String variables are used for everything that cannot be represented by a plain integer, and you can usually both read from and write to them. However, it depends on the Qs variable how the simulator reacts. Sometimes your changes will be taken over by the running simulation (such as when you change the in/out state of a row of circuit breakers) and sometimes it will be essentially ignored (such as when changing a display line on a CDU). And in many cases, you first read the variable, modify a part of the string locally, and send back the complete string.
Take care that leading and trailing spaces in the Qs variables are meaningful: do not delete them, and be careful including them when required. For example, the CDU lines always need to be exactly 24 characters (or 48, or 72, depending on what you want to achieve).

After you connect to a server, a continuous stream of Q variables will be pouring into your add-on program. You likely want to keep a list of the variables you are interested in, and store their latest value locally for reference when you need it. The variables you're not interested in can be simply ignored.

To parse the incoming message lines, you can inspect the first character (Q). A Q always means that there will be a category (h, i, or s) and an equals sign (=) followed by a value. The value is always an integer when the category is h or i, and a string otherwise. If something does not match this pattern, notify some human operator and ignore the message.

PSX Network Modes

This documentation is not authoritative. The official PSX documentation on the Aerowinx web site always takes precedence.

Within the Qh and Qi categories, subclasses of variables exist that exhibit a common behaviour. These variables share a common network mode.

PSX has the following network modes (in order of complexity):

C -- Continuous

Variables that are continuously sent to the network, no matter whether they have changed or not. A new value will come in a very short time.

E -- Econ

Variables that are sent to the network only when they have changed. Add-ons may store their value and use it until the next update comes.

D -- Delta

Variables that are sent to the network only when they have changed. They are used for momentary action switches and for infinite rotary delta values. Add-ons should never store these, but only react on their appearance, as they do not give the button position but only the fact that the button is pressed or rotated.

B -- Big Momentary Switch

Same as Econ, but partially Delta. These are the big black squared pushbuttons with momentary action and in-built lights. The momentary action is like Delta, the lights are like Econ.

M -- MCP Momentary Switch

Same as Econ, but partially Delta. These are the black squared MCP pushbuttons with momentary action and in-built lights. The momentary action is like Delta, the lights are like Econ.

G -- Guarded Momentary Toggle type 2

Same as Econ, but partially Delta. These are the guarded toggle switches with momentary action.

F -- Guarded Momentary Toggle type 4

Same as Econ, but partially Delta. These are the guarded toggle switches with momentary action.

Suggested next page: The PSX Lexicon >>