|
| 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. It is heavily recommended to poll once between every 45 and 75 seconds, randomly timed so that the average server load is constant. 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 multiple messages in a short time. Please set your HTTP(S) timeout 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 because that 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. In order to reduce the system load, there currently (2023-11-04) is a gap detector in place that won't honour poll requests that are closer than 20 seconds after the previous poll request. There are clients out there with a poll rate set to once per 5 seconds. This is not acceptable. ACARS in the real world really is not 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. Position MessagesTechnically identical to Progress and Telex, but with a different payload. These can be parsed by a machine, for example to make a graphical position plot.PosReq MessagesRequest the return of a Position Message. Payload is ignored.Poll MessagesA special one. This message polls the communication server for pending messages directed to your callsign. You receive a list of pending messages back if there are any. Meant for message retrieval by true ACARS stations, airborne or ground-based.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 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. Peek MessagesAnother special one. Comparable to POLL, but returns all messages directed to the callsign that are still in the queue. 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.DataReq messagesThe packet payload is considered to be a file name, and the corresponding file out of the upload store is returned to the requestor. This is a more technical interface, described on a separate documentation page.InfoReq messagesThe packet payload is considered to be an information request, of the form "request icao". Request can be one of "metar", "taf", "shorttaf", "vatatis", or "peatis". The requested weather information is fetched live from the NOAA servers and returned in the reply packet straight away.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 | For more information, mail to hoppie@hoppie.nl |