This specification describes the record-based protocol for transmitting TopoVista elevation data. It is a successor to TVTP and is designed to allow the use of smart routers that may aggregate requests and/or cache data. This protocol is known as AGILE, for AGgregate Interest LEvels.
All messages are transmitted as UDP datagrams. This imposes an upper limit of 64KB on the size of a request or response. As a practical matter this limits tile sizes to 256 x 256.
UDP message transmission is unreliable. This protocol is intended to be robust against occasional dropped messages, although possibly with delays that may be perceptible.
The protocol is defined in terms of a client and a server. These labels reflect the roles of the participants in the protocol. A router plays both roles, acting as a server to downstream clients and as a client to an upstream server.
A server receives messages on a known port (normally 4747). A client initiates a session by sending a message to a server. Clients are distinguished by their points of origin: each unique {ipaddr,port} pair identifies a different client. Server responses to a client are sent back to the originating port.
There are only two kinds of messages: requests, sent by the client, and info, sent by the server. They are not paired: The client keeps the server advised of its needs, and the server responds on a best-effort basis, but there is no one-to-one correspondence.
A TopoVista tile record is the basic data quantum. Clients declare interests in individual tile records, not whole tiles, and server responses generally consist of individual tile records.
A client maintains a list of tile records for which it has an interest and associates a priority with each record on the list. This interest list forms the request message it sends to the server.
A client sends its entire interest list to the server:
Receipt of a tile record from a server presumably changes a client's interest in receiving that record again, but this can be inferred by the server and so the client is not obliged to send an updated list in this case.
The 60-second heartbeat message serves as positive confirmation to the server that the client is still hoping to receive data, and also provides redundancy should a previous request or response have been dropped by the network. However, a client is not required to wait 60 seconds before reissuing a request that is identical to its predecessor.
Clients must be prepared to accept (or discard) any valid message from a server regardless of whether it corresponds to a current or past interest.
A server receives requests and sends data. The protocol gives the server great latitude in deciding which requests to service and in what order. Good server (or router) design is important but is not part of the protocol spec.
A normal DATA message transmits a single TopoVista tile record from server to client.
The server can also send a special UNAVAILABLE message to indicate that data for a tile cannot be provided and that this condition is not expected to change. The UNAVAILABLE message identifies a single tile, by tile ID, and includes a bitmap identifying the tile records within the tile that are considered unavailable.
In deciding what to send, the server presumably is guided by request messages from its clients. A request message from a client supersedes all previous requests from that client. If a client has not been heard from after some number of heartbeat periods have elapsed, the server is justified in treating it as if it has no more interest in anything.
After sending a record to a client, the server should not send the same record again until it receives a fresh request. If a request arrives nearly coincident with the send, the server can choose to treat this request as preceding the send.
A request message is an 8-byte HEADER followed by one or more 8-byte REQUESTS.
The HEADER is:
'T' 'V' 'R' 'P' '\00' '\00' '\00' '\00'
Each REQUEST specifies a tile ID, priority, and bitmap, where the bitmap specifies a set of records in the tile that are all desired with the same priority.
The format is
TTTTTTTT TTTTTTTT TTTTTTTT TTTTTTTT
PPPPPPHz abcdefgh ABCDEFGH IJKLMNOP
where
TTT..TTT is a 32-bit tile ID
PPPPPP is a 6-bit priority
H is set if the tile header record (flag=0x10) is wanted
zabc..gh are set for data records (0x20 through 0x28) wanted
ABC..NOP are set for error records (0x41 through 0x50) wanted
Note that there is no way to request the largest records if a tile exceeds 256 x 256. Furthermore, there is no way to request error record 0x40, which always contains a single zero, nor error record 0x51, which is not normally transmitted and is a very inefficient representation of an array of zeroes.
A bitmap of all zeroes requests nothing but is not an error.
If multiple requests within a message specify the same tile record, the receiver may arbitrarily use any of the associated priorities.
An INFO message is a 12-byte header possibly followed by a tile record. There are two kinds of info messages:
The header specifies a tile ID and a tile record bitmap. Its format is:
'T' 'V' 'I' 'N'
TTTTTTTT TTTTTTTT TTTTTTTT TTTTTTTT
U00000Hz abcdefgh ABCDEFGH IJKLMNOP
where
TTT..TTT is a 32-bit tile ID
U is set for an UNAVAILABLE message
Hza..NOP designate tile records as in REQUEST messages
For a DATA message, the U bit is zero,
and the header is followed
immediately by a TopoVista tile record.
Exactly one of the Hza..NOP bits
should be set to designate the particular record.
This bit must agree with the flag value in the fifth byte of the
tile record (the 17th byte of the INFO message).
An UNAVAILABLE message designates one or more the tile records as
unavailable.
The U bit is set, and one or more of the Hza..NOP
bits are set to designate unavailable records. No data follows
the header, so the entire datagram is 12 bytes long.