Hoppie Home
PSX Router Home
Project Progress
Documentation
Download
09-Feb-2010 07:47Z
1.5Mb
|
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
>>
|