PS1 Broker Documentation |
Be careful that this is jurassic software.
InstallationThe installer will do it all for you. Configuration is not required in most cases.UseThe 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 BrokerMost 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 commandsregister 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 TricksIf 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 Listin 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.
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. :-)
|
| © 2024 Jeroen Hoppenbrouwers All rights reserved, including those for text and data mining, AI training, potato stamps, and similar technologies. | For more information, mail to hoppie@hoppie.nl |