-*- mode: text -*- ############################################################################### ## ## ## File: NOTES-AUTHORS ## ## Author: Wolfgang S. Rupprecht ## Created: Mon Feb 15 11:59:17 PST 1999 ## ## Contents: NOTES for rtcm-sc104 program authors ## ## ## ## Copyright (c) 1999 Wolfgang S. Rupprecht. ## ## All rights reserved. ## ## ## ## $Id: NOTES-AUTHORS,v 1.9 2004/10/28 21:49:39 wolfgang Exp $ ############################################################################### This document attempts to define the current best practices for programs connecting to the GPS differential correction server at dgps.wsrcc.com on port 2101 (rtcm-sc104). The rtcm-sc104 server sends a native GPS "RTCM SC104" byte stream across the tcp connection. A simple server may just move bytes from the tcp steam to the tty io steam. The following code fragment will do this job just fine. while (1){ putc(getc(net), gps); } PROGRAM ID: It is highly recommended that the client identify itself at startup. (2004-10-26: This line is now mandatory. See the port-scanner notes at the end. -wsr) This will aid in tracking bugs and other network connect problems. The recommended startup ID line is: "HELO hostname program_name version_number_string\r\n" This is an example of the dgpsip client running on a local machine: "HELO scoville.wsrcc.com dgpsip 1.20\r\n" The hostname is just some involatile name the host knows itself by. It does not have to be an officially registered hostname. In fact, in the case of hosts that dial up the internet with dynamically assigned IP addresses, it is very desirable to not use the official hostname for this. It would be preferable to use something that won't change every time the host dials up. If there is no hostname available that serves such a purpose, a user name or a software ID number will do fine. If nothing serving this purpose is available a simple "-" in place of the hostname will do fine. (The idea is not to be big-brotherish but just to give me some chance at figuring out what is going on when I get a string of a zillion short connections, all of them dropping the TCP stream without a graceful close. It feels like there is some software client that just crashes, and I'd like to find out which one it is.) The program name and version numbers should be the name and version number the program is commonly known by. Please use underscores or dashes (or have the words run together) instead of spaces within the names. Names with embedded spaces make it impossible to reliably parse the line. STANDARD DEVIATION REPORTS: It is also highly recommended that client software has an option to submit periodic standard deviation reports. This allows us to automatically generate summaries of how well the system is working for folks around the world. The format of the standard deviation report is as follows" "R 37.55 -121.94 22.20 -- 16 1.53e-05 8.20e-06 4.85e-15 2.1 4.0\r\n" The "R" signifies a Report. The first two floats are the latitude and longitude as reported by the gps. Only two digits of lat/lon are needed. This gives us a 1.5 mile radius from the user's actual position which is good enough for our calculations. I really *don't* want data any closer than that. The third float is the height in meters as reported in the NMEA GGA "alt" report. The next number is the number of samples received from the gps via the NMEA sentences (or via other means) at the time of this report. The next two numbers are the standard deviation in latitude and longitude. The next number is the standard deviation of the height. If these are not calculated the fields may be marked with a "-". In that case a one-time report of the following is just fine. "R 37.55 -121.94 22.20 -- 16 - - - 2.1 4.0\r\n" Next is the average HDOP. This is just the HDOP as reported in the NMEA GGA "hdop" report averaged over the number of recorded samples. Next is the average number of satellites in view. Again this is just the NMEA GGA "number-of-satellites" averaged over the recorded samples. ACCEPTABLE VARIANTS: If the data for any field isn't available those fields may be marked with a "-". If desired, all missing fields at the end of a line may be omitted. eg. "R 37.55 -121.94 22.20 -- 16 - - - - -\r\n" May be shortened to: "R 37.55 -121.94 22.20 -- 16\r\n" If the initial (third-field) height information isn't available, it may be either specified as "-" or left out entirely. Either form is acceptable, since it can be unambiguously parsed. "R 37.55 -121.94 - -- 16\r\n" "R 37.55 -121.94 -- 16\r\n" An older (but still valid) form of the report is as follows: "R 37.55 -121.94 -- 16 7.88e-05 2.47e-05\r\n" The fields are lat, lon, "--", number-of-samples, sdev-lat, sdev-lon. This is also unambiguously parsable and will be acceptable. REPORT FREQUENCY: If the standard deviation is calculated a report should be sent in at decreasing frequencies, so as to not overload the server. It is recommended that the first report be sent no sooner than after 16 samples. The next at 32, 64, 128, 256, and each increasing power of two after that. Again these frequencies are just a compromise between getting a number from an impatient user that may only stay connected for a few seconds and a hedge against filling up the log file with thousands of redundant reports from users that stay connected for 10,000 seconds. If the natural data collection period of the client program is longer than the the 16 seconds, please don't sweat it. Just send what you can when the program works it out. Please do try to exponentially back off on the reports from that point though. I don't really need a report say every two minutes for weeks at a time. RECONNECTING TO SERVER: The RTCM-SC104 server will occasionally be upgraded and restarted. It is not possible for the new server to inherit the connections from the old server. The TCP connections to the client will therefore be dropped as the old server exits. When this happens, it is perfectly acceptable for the client to turn right around and attempt to open a new connection. In fact it is highly encouraged. The only proviso is that it would be very nice if the client were to try to reconnect with decreasing frequency. The recommendation is to try to reconnect with 1 second delay, if unsuccessful, try again in 2 seconds from the last attempt, if still unsuccessful try 4 seconds from the last attempt etc. Each attempt should double the delay from the previous attempt. It is perfectly ok for the client to limit the maximum delay between attempts to 60 seconds. That is, once the delay timer reaches 60 seconds, it is acceptable to try every 60 seconds with no further exponential backoff. If the client reconnects to the server it is highly recommended that it issue a new position report as soon as convenient. This will let the server know that a GPS is connected and will trigger the slightly less efficient small-packet/low-delay mode of operation. UPCOMING EVENTS: At some point in the future the load on the dgps-ip server will warrant classifying the dgps-ip clients into two types; INTERACTIVE and BULK. Interactive clients are GPS's and other devices that need timely differential corrections. Bulk clients are ones like selective-availability logging programs that are only interested in recording the data. The reason it pays off to split out the bulk clients is that there is currently more packet overhead than packet data in 32-byte interactive dgps-ip packets. It would really be nice to send bulk data in 512-byte packets. The current server already understands the BULK command and also has some heuristics to try to determine if a GPS is connected. Sending the string "B\r\n" to the server will switch into user-requested bulk mode. Sending a position report string "R lat lon\r\n" will shift into interactive mode. Sending nothing will start a timeout which is currently set at ten minutes. After the timeout the server will start sending BULK data. For this reason it is recomended that software that actively talks to real GPS's send at least one position report string within the first minute or two. PORT SCANNERS AND OTHER FORMS OF ABUSE: Due to increased abuse activities I've had to make the HELO line mandatory. Some hosts were opening over a dozen connections and keeping them open without sending any data that would make me believe they were really dgps-ip clients. My suspicion is that it is some port scanner gone crazy. Please don't abuse the server. I've already had to block one large Redmond based company (that is best known for putting out swiss-cheese operating systems) for being jerks and opening tens of connections per second from the same host in rapid-fire fashion for minutes at a time. # # end #