|
| ACARS server API |
|
|
Hoppie's ACARS is based on store-and-forward. Stations sending a message will contact the ACARS Network (in real life a network of "cellular" VHF stations, simulated one single Web site using HTTP) and put their message in a queue. The queue is maintained for 24 hours (or less, if the traffic volume increases). Within this time, the addressed station (callsign) may pick up the message. Everything is based on polling, not on permanently open connections that get asynchronous notifications. There are many independently written ACARS clients out there and with no real hard definition available for the message payload, some clients have trouble with some formats. This actually is exactly like in real life... so it pays off to be conservative with your formatting. Also real-life ACARS is usually paid for by the character, the system comes from the 1970s and is a far cry from today's unlimited gigabyte-class networks. So do not send kilobytes of stuff. It just is not realistic. The Connection ProtocolConnect to the Web server with the following URL (subject to change):
The intention is that each ACARS client (station, both ground and aircraft) does a single connect every minute or so. During this brief connect, the ACARS server will look for pending messages to the station, and accept anything sent from the station. Since the vast majority of connect moments will not result in either a send or a receive, as nothing happened since the previous connect moment, the server load is 99% determined by the polling rate of all stations together. You can follow this at the online overview. It is heavily recommended to poll once between every 45 and 75 seconds, randomly timed so that the average server load is stable. If you expect a message, such as right after you sent a request, you may increase the polling rate to once per 20 seconds for a short time. On the other hand, if you want to send something, there is no delay required. Just please don't sent many messages in two seconds, not even when you represent multiple call signs or are an ATC station. As an airplane client developer, wait to start polling until your aircraft has sent its first message! Nobody just listens on ACARS for incoming messages. They always first ask for something -- ATIS, weather, logon to CPDLC, anything. Without that first request, nothing will move, and starting to poll just adds load to the system for no reason. As the majority of aircraft that are polling my server never even ask for anything, imagine the load relief we would get if they never started to poll in the first place. Please set your HTTP(S) connection timeout (this is not the polling rate) to 15 seconds. If you cannot get a poll connection in 15 seconds, please skip this attempt and come back after your normal random delay between 45 and 75 seconds. Do not retry immediately, because this will likely result in the same timeout and the only way out is to reduce the server load, which needs all clients to work together and slow down. If you want to send something, you may retry after a few seconds. ACARS in the real world really is not such a fast system at all; due to various system delays and overcrowded VHF stations, it can take surprisingly long for a request-response cycle to complete. If SATCOM is involved, it can take even longer.
Request Variables (GET, POST)You need to supply a few data items with each request. You may use either the GET or the POST protocol, or both intermixed.
.../connect.html?logon=gFR54Fr&from=KLM&to=KLM123&type=telex&packet=This+is+a+test.
For the syntax of some packets, such as ADS-C, CPDLC, progress, etc. please see the message log (link on the left). The server does not parse the message in the vast majority of cases, it just relays it, so all ACARS clients need to be careful about what they do. This is exactly like ACARS in the real world. Progress MessagesNot yet processed by any machine, just treated as plain text. Contains out/off/on/in times and ETA. Airborne ACARS stations may send progress messages automatically to the dispatch station when flight events occur. See the ACARS manual for an exact description of these events.CPDLC (and ADS-C) MessagesData traffic meant for processing by airborne or ground equipment used for ATC (Controller-Pilot Data Link Communications). Contains machine-readable data which should not end up directly in an interface, but is processed and workflowed via dedicated software. The "@" signs in CPDLC messages are line feeds for presentation purposes but do not really mean anything. Note that the ACARS communication station has nothing to do with any of these messages; they need to be 100% handled by the clients. You need an online ATC station to talk to. There's some extra documentation on the CPDLC development interface page and same for ADS-C. Telex MessagesThese contain the bulk of all non-specialised traffic. Anything can be sent as a telex. Note that in most cases, you will want to use POST protocol to avoid having to URL-encode the packet and/or run into maximum URL length limits. Good practice is to always keep URLs under 256 characters.
Ping MessagesJust echoes OK, to test the connection with the communication station. This is the equivalent of an ACARS Link Test to the media layer.In case the packet is not empty, each word of the packet is considered to be an ACARS call sign. The message returns a packet with the call signs of the list that are actually online. This is not a real-time ping request all the way to the remote station and back. A special fake call sign is ALL-CALLSIGNS (case-sensitive) which will return a list of all recently seen call signs. This only works for the ping type of message.
ALL-CALLSIGNS has been disabled as too many stations used it too
often, which is unsustainable in heavy load situations. There are no good
reasons that I know of to ping ALL-CALLSIGNS every 10 seconds. If you are
making an ATC bot and the aircraft does not call you, don't call them! And
if you absolutely must, ask for the call signs every 10 minutes, not every
10 seconds.
The POLL command is the one the client needs to perform regularly to see
whether there are new messages waiting. About once per minute is fine.
Faster polling is unrealistic in most cases. However if you expect a
message, such as immediately after you have sent a request, you may poll
once a bit faster, like once after 20 seconds. Remember that there nearly
always is a human being in the loop on the other end, so hammering it won't
help. Even CPDLC is never about time-critical messages.
Another special one. Comparable to POLL, but returns all messages
directed to the callsign that are still in the database (last 24 hours).
This can be a whole lot of messages so don't use this without giving it some
thought. No 'relayed' time is recorded, and the peeking station is not shown
as being on line. Meant for message retrieval by automated processing
devices, such as event time loggers for virtual airlines.
Please do not use this message type for general operations. If a
normal aircraft or ATC station uses peek instead of poll, a
lot of things will go wrong.
VATSIM ATIS information comes from their live servers. The system tries to
match the given ICAO to a VATSIM ATC callsign, if needed by dropping a
leading "K". Only ATIS and TWR stations are polled.
PilotEdge (PE) ATIS comes from the PilotEdge server and are looked up by
exact ICAO code without translation.
The requests are independent of the network your account is associated with;
in all cases you need to specify the correct request type, there is no
default "atis" request (yet).
|
| © 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 |