PS1 Broker Documentation

Hoppie Home

PS1 Broker

Project Progress

Downloads

TCP/IP Setup

Installation

The installer will do it all for you. Configuration is not required in most cases.

Use

The Broker is a run-and-forget program. You have to set it up once, and after that, just run it and it will work.

First open the File/Setup menu and fill in the path to the directory where you have installed PS1.3. Usually this is c:\ps13. You can also set the slider to 5 seconds, which is the time messages will remain visible in the PS1.3 outside view window. On slower systems, the High Priority selection might improve responsiveness of the Broker while PS1 is running in the foreground. Then click Ok and the setup is saved in etc/747brok.ini. If you get an error here, create the etc directory manually and try again. The other settings are not required for basic operation with PS1.3.

You can now run PS1.3 (actually, you can switch PS1.3 on and off at any time) and enable External Data Link (in the PS1 Preferences menu).

Next, switch on PS1 Updating (File/Update PS1). The Broker should announce this in the log window. The Broker will follow PS1.3 from now on, as you can see in the various View panels. If the Broker finds PS1.3 on startup, it will immediately select PS1 Updating.

ONLY in case you want to get data from somebody else's Broker and feed that data to your clients, fill in the Master Broker's hostname and port number (using the hostname:port notation, where 'hostname' may be either a name or a four-number-with-dots IP address) and check the "Proxy" box. Default port is 1863.

You may also have your own Broker listen out on another port than the default 1863; if you want, change the port in the first box of the Setup dialog.

Connecting to the Broker

Most people will now just start the add-on applications they want, such as SquawkBox or the SceneryInjector. However this documentation assumes you are a developer.

Write an application or use Telnet to connect to the Broker. The Broker listens on port 0x747 or 1863 decimal and uses line-terminated plain ASCII communications.

You can give the Broker several commands. A command always consists of a command word, followed by one or more data words and ended by a line feed. Spaces may be used to separate words. If words should contain spaces, either use double quotes " " or braces { } to indicate word boundaries.

Available commands

register appName (status) To register your application, so that the Broker can display a more meaningful name for the client. appName is the name you want to have your application put in the Broker "Connected" list. The optional status is something you can decide on yourself, please use something like "Running" or "Active" etc. Re-register when the status changes.

broadcast message To broadcast the given message verbatim to all connected clients. Clients are assumed to display all incoming things that they do not understand to the user in some form.

get key (key key...) Retrieve data. Only existing keys are returned, no error messages are given. Data is returned in the following format: data (key value key value key value...). Most data is in native PS1.3 format, which might be 10 or 100 times multiplied. A special command is get all that returns all available keys and data.

put key data (key data key data...) Puts data into the Broker.

notify key (key key key...) Registers a notification trigger for the given keys. Every time a key changes in the Broker, your client will immediately be notified (by data messages). You will get initial values immediately after the notify command.

exit Terminates the connection to the Broker.

Tips and Tricks

If you want your network link to be constantly monitored, start sending ping messages to the Broker each five seconds:
put broker.ping something
After the reception of the first ping, the Broker will allow you at most ten seconds to send the subsequent ping for the lifetime of your connection. You may put whatever you want in 'something' as it is never looked at.

Please try to group all keys of put and get commands on one line, since this significantly reduces communication overhead. But take care that within one line, all double keys are removed. If you need to change the same key twice (this is typical for double keypresses), use two separate put commands. They will result in two data messages.

You can create your own keys, just by putting them into the Broker. Other clients can retrieve them normally. But you cannot overrule PS1.3 keys.

There is no protection against multiple clients trying to update the same keys. This type of conflict should be remedied by a protocol between the involved clients (like a set-and-test of a designated key).

It is a good idea to send all incoming messages that are not data messages to some kind of console log. These messages are often error messages, which should be countered by changing your program, or line status messages that are broadcasted over all clients, like the fact that PS1.3 updating was disabled or that the scenery generator crashed.

Key List

in means that this data is sent to PS1; if you change the data, PS1 will follow.
out means that this data is read from PS1; you can not change it.

ackInternal use by the Broker for ATC/ACARS acknowledgment. Do not use.
alto True altitude above MSL in feet.
altbasi Base of altostratus layer in feet above MSL divided by 10. Must be lower than top of altostratus, else no layer visible.
altimi Altimeter setting at MSL in inches of mercury times 100.
alttopi Top of altostratus layer in feet above MSL divided by 10.
arxi ACARS telex receive, max. 120 characters
atxo ACARS telex transmit, max. 100 characters
bnko Bank in degrees times 10, also negative.
como Active COM frequency in MHz times 100.
flpo Flap lever position.
geao Gear lever position.
gndo Ground speed in knots.
hdgo True heading in degrees times 10.
hrso UTC hours.
lado Latitude degrees.
lamo Latitude minutes times 100,000.
laso Latitude "sign", "n"orth or "s"outh.
lodo Longitude degrees.
lomo Longitude minutes times 100,000.
loso Longitude "sign", "e"ast or "w"est.
sb.metarLast used METAR by SquawkBox weather generator. Only available when SB747 is connected.
mino Minutes UTC.
nimbasi Base of nimbus layer in feet above MSL divided by 10. Must be lower than top of nimbus, otherwise no layer visible.
nimtopi Top of nimbus layer in feet above MSL divided by 10. Must be lower than base of altostratus.
pito Pitch in degrees times 10, negative if required.
ps1diro Absolute path to the installation directory of PS1.3.
raini Rain mode 0, 1, or 2. No rain visible if no nimbus layer present.
rrxi Radio reception of COM message to PS1. Max length is 80 characters.
rtxo Radio transmission of COM message from PS1 (use the "K" key in PS1 with FMC keyboard off). Max. 25 characters.
sbro Speedbrake lever positions.
tcasTCAS intruder output. Contact author for more information.
tempi Temperature at MSL in Celcius.
thuni Thunderstorm mode, 0, 1, or 2.
trko True track in degrees times 10.
turbasi Base of turbulence layer in feet above MSL divided by 10.
turinti Intensity of turbulence, 00 - 99.
turtopi Top of turbulence layer in feet above MSL divided by 10.
varo Local magnetic variation from FMS/IRU database. Unknown (zero) if airplane is in polar regions.
vero PS1 version times 100, currently 130.
visi Visibility in meters divided by 10. No fog visible if no nimbus layer present.
wavi Sound file to be played in PS1. This function requires a full absolute path name to a WAV file on the client's machine running PS1, or a relative path starting from the PS1 directory, or a path relative to the Broker that must start with ~broker/. This is the most buggy function in the whole system.
whidiri High wind direction (FL350) in degrees relative to true North.
whigsti High wind gusts in knots. No gusts if equal whispd.
whispdi High wind speed in knots.
wlodiri Low wind (ground) in degrees relative to true North.
wlogsti Low wind gusts in knots. No gusts if value equals wlospd.
wlospdi Low wind speed in knots.
wsi Probability of windshear encounters, 00 - 99.
wxri 1 = Weather injection enabled, 0 = disabled. Must be set to 1 before any of the weather variables is taken into consideration by PS1.
xpdo Transponder setting, four octal numbers. Value is zero if both transponders are off.

When making your own keys, try to stick to this rule: prefix your keys with a shorthand notation of your application: app.key. In this way the "owner" (= writer) of a key can be easily identified. Why does the Broker not prefix ps1. before every key? Because I was first. :-)


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