APRStt SPECIFICATION Version 2.2 31 May 09 ---------------------------------------------------------------------- 31 May 09 Added details of variables used for sysop setup 16 May 09 Incorporated lessons from Dayton test 05 May 09 Changed symbol to use existing overlay-BOX symbol 28 Apr 09 updated to version 2.1 for implementation 07 Oct 08 updated to version 2.0 for 19 May 08 original creation of 2.0 to simplify the original APRStt APRStt KeyPad: -------------- Although it was slow to standardize, the following DTMF keypad layout is assumed for APRStt. This was derived after long study of all the various alphanumeric implementations already used in ham radio. See the summary of all existing applications: http://aprs.org/aprstt/radios.txt +------------------+ This figure shows the standard Touch Tone Key | 1 2 3 A | pad with the standard Alphabetic alternate | ABC DEF --> | definitions that we will use for APRStt. For | 4 5 6 B | Alphabetic text, the letter A would be one |GHI JKL MNO <-- | press of the "2" key, B would be "22" and C | 7 8 9 C | would be "222". To enter a digit "2" within |PQRS TUV WXYZ del | text, it would be "2222". If two adjacent | * 0 # D | letters use the same key, then press the "C" | space OK! | key between them. Multiple presses of the # key +------------------+ can generate punctuation in the order ?!'.,-/ etc CALLSIGN FORMAT: ---------------- The format for a DTMF callsign is: AcccccccccccVK# Where.... A signifies it is a callsign DTMF string ccc... callsign in two-key DTMF V oVerlay character (0 -9 or A-Z) K checksum digit (The units digit after summing all keys) sum ABCD keys as if they were HEX. # end CALLSIGN ENTRY METHOD: Although the general TEXT-to-DTMF method used for APRStt is the muiltipress method, this can make some callsigns too long to fit into a 15 key DTMF memory on some HT's. FOr this reason,FOR CALLSIGNS ONLY, APRStt uses the two-key method used by Echolink and Kenwood/Yaesu in those 300,000 DTMF text-messaging radios they sold in the late 1990's. THis method uses the digit of the key with the letter on it, followed by either the A, B, C or D key to show which of the letters the digit represents. For example, the letter L is 5C showing it is the 3rd letter on the 5 key. To enter a numeric digit, just a single digit key is needed that is not followed by one of the ABCD keys. STRING LENGTH: The above two-key method can assure that all callsigns can be encoded into a minimum digit length of 15 DTMF digits IF the overlay character is chosen as a single numeric DIGIT. This makes sure that users with radios with only 15 key memories in their DTMF memory can still use APRStt. However, users with 16 DTMF key memories may use any ALPHAnumeric overlay character which takes two V digits. Notice that for special events, APRStt users can use TACTICAL NUMERIC 3 digit calls that greatly shorten these tone bursts. For example A9A2B42A7A7C71# Station WB4APR with overlay "7" A12306# Station "123" with overlay "7" APRStt TYPE KEY: The first DTMF key in any APRStt DTMF string indicates the type of APRStt entry. A # key always ends the users data. A * key is used to terminate a datra field, but indicate that more information will follow: A.....# indicates a Callsign B.....# indicates some position data C.....# indicates comment text or status D.....# indicates message text PRECURSOR "#" KEY: (consider this an open item. Usage in APRStt has not been finalized). Since APRStt may share a radio channel with other DTMF functions (such as repeaters) and VOIP systems, a user may preceed his APRStt string with a leading # key that may trigger these other systems to ignore the following digits. This may work in many repeater controllers. Thus, we can use # as an optional start of all APRStt sequences to force the normal repeater to ignore the remainder of the APRStt sequence. EDITING KEYS: The keypad editing keys used by the APRS radios to correct entries on the fly are not generally used on APRStt, becuase the DTMF user does not have a keypad display so he can see what he is typing. But if we do use these for APRStt, the following will apply in APRStt TEXT. (This does NOT apply in a callsign, which must be correctly entered ONCE into DTMF memory).: A - ADVANCE to next letter. THis key is used as a digit separator when text sequential letters share the same key. B - A backspace character (cancels the previous key) C - CANCEL. THis aborts the whole string typed so far D - Is reserved for future use. * - is used as s field separator (like a comma for example) # - is the ending key (like an ENTER key) CALLSIGN-12 SSID: By default, an APRStt user's callsign will be assigned an SSID of -12 when it is gated over to the APRS system. This makes it easy to destinguished APRStt users from other native APRS stations and callsigns. CALLSIGN SUFFIX SHORTCUT: Since shorter calls take less airtime, APRStt allows the user to use his shorter 3 character callsign suffix as long as there are not local conflicts with other calls in the same APRStt area. On receipt of an abbreviated callsign, APRStt will look for a match with full callsigns it has already heard and if no conflict, will expand the call when gating to APRS. If there is a conflict, it will ask for a full call. TO further shorten the call, you do not even have to use the 2-key method, just the matching digits of your suffix. The overlay digit can be used locally to resolve any callsign conflicts. So for me it would be "APR" and that would short cut to 277, and adding a "9" overlay would result as: A27795# (checksum 35 = 5) The APRStt engine will scan its recent list of active APRStt users and do a RIGHT-END-MATCH. If there is a match, then it already knows the callsign. If there are multiple matches, then there is a conflict, and APRStt will request the full callsign. Local users that have conflicting simplified suffic calls can negotiate different overlay digits. The FULL callsign must have been received within the last 2 hours to be valid. Otherwise the short, all digit callsign is assumed to be a tactical call and is passed along to APRS in its literal form: 277-12 (with the -12 SSID) with overlay of "9" in this case. MULTI-STRING-DELIMITER: Generally, the * key is used as a field de-limiter. A good example is sending the simplest position report of Bxy* which places the user on the map in an XY grid. The * terminates the position field, but indicates that there is more to follow. Usually, what follows is the full callsign replayed from DTMF memory. This way, the APRStt decoder can be sure to associate the BXY* with the sending callsign. APRStt POSITION FORMATS: ------------------------ Positions, Comments, Text and Messages can be sent with APRStt. These are usually sent first, separated with a "*" key and then ended with sending the callsign from DTMF memory. All position formats begin with the "B" key, and the second digit indicates the "type" of position format. One, some or all position formats can be supported at each individual APRStt gateway depending on its exact applicaiton needs. For example, the 1 digit format can be interpreted as marathon mile marks, or for an XY grid as we did at Dayton 09. Here are the formats: B0x* One of 10 special positions B1xy* 1 digit XY ( 10 mi in 60 mi area) (default) (or 1 mi in 10 mi area) (or.1 mi in 1 mi area) B2xxyy* 2 digit XY ( 1 mi in 60 mi area) (default) (or .1 mi in 10 mi area) (or 60 ft in 1 mi area) B3xxxyyy* 3 digit XY ( .1 mi in 60 mi area) (default) (or 60 ft in 10 mi area) B4xxxxyyyy* 4 digit XY ( 60 ft in 60 mi area) (default) B5zzzmm* at bearing zzz range mm miles B6EEENNN* SAR UTM Grid - Easting and Northing B7RRRMMM* Road RRR, Milemark MMM B8......* Table interpolation B9... * TBD There is a SETUP file for the SYSOP to establish the various parameters to customize these different formats for his particular application. See Appendinx-A below. APRStt PROCESSING: Above defines how a USER identifices himself. The rest of this text file describes what the APRStt processing does to convert that call sign in to APRS information for transmitting onto the APRS channel To setup any APRStt system, the APRStt engine needs to be configured with some basic information. Since the output of the APRStt engine is an APRS object each time a new DTMF callsign identification comes in, the APRStt engine has to have a basic template for the rest of the local data that needs to be added to the basic OBJECT packet that will go out on APRS. ------------------------------------------------------------------- Creating the APRS object ------------------------------------------------------------------- APRStt OBJECT FORMAT: The following specifies the use of the APRS object format for the translation of the APRStt user data to the APRS system. These formats must be followed EXACTLY since multiple APRStt receivers may hear a single DTMF string and may generate duplicate packets. These packets MUST BE identical in the APRS-IS so that the normal existing dupe elimination system will only take one cooy and ignore the others. First is the AX.25 header for the packet data: TTCALL-SS>APTvvv,WIDE1-1: AX.25 Header Where TTCALL-SS is the AX.25 Source address of the APRStt Gateway Where APTvvv is the software/hardware version number Where WIDE1-1 is the typical one-hop or less path for the data Next is the avctual object format as follows: ;CCCCCC-12*HHMMSS/DDMM.yyN?DDDMM.xxWA... Where ;CCCCCC-12* is the APRStt user's callsign (object Name) where HHMMSS/ is the time field when heard (local time) where DDMM.yyN is the latitude for the object Where DDDMM.xxW is the longitude for the object Where ? and ...A specifiy the use of the BOX symbol with ? overlay Where ... are additional information fields ADDITIONAL-INFORMATION-FIELD: Like any APRS object or position packet, what follows the Symbol byte to the end of the packet is a free field text area for additional information from the APRStt engine or from the user. The max length permitted is 43 bytes, though shorter packets are encouraged. There are several commonly used additonal data fields in APRS and some additional restrictions on how they are used as follows: CSE/SPD - Not applicable to APRStt PHGphgd - Not applicable to APRStt FFF.FFFMHz - Frequency, very important to APRStt /CCCCCCCCCC - Mic-E comment. These are all 10 bytes in length xxxxxx... - anything else is free field comment with leading space free text/CCCCCCCCCC - example combinations FFF.FFFMHz/CCCCCCCCCC - example combinations FFF.FFFMHz xxxxxx.../CCCCCCCCC - example combinations Unlike traditional APRS packets that always arrive intact as a complete packet, these fields in the APRStt gateway will come into the APRStt engine in multiple transmissions. The APRStt engine will assemble these separate fields into the outgoing packet. Each addition of a new piece of info will cause an update to the previous packet and a new transmission of that altered format. Here are the incoming DTMF strings and the resulting APRS packet output: AcccccccccccVVK# - CALLSIGN ONLY: This will generate the above OBJECT format with the position synthesized from the known location of the APRStt station and the desired APRStt list to appear in the vicinity. This is usually accomplished by didling the "yy" bytes of latitude hundredths of a minute. The Additional-INFO-Field will be added by the defaults loaded into that instance of APRStt to match the event, or situation of the APRStt installation. It can contain frequency and TONE and RANGE for example if it is a repeater location... BnX..Y..*CALLSIGN# - Position Data: This will transmit a new packet with the position info provided CFFFFFF*CALLSIGN# - Frequency data: This exact 6 digit format will be expanded to "FFF.FFFMHz". If an existing frequency exists in the packet field, then it is overwritten. If an existing frequency does not exist, then the existing Additional-Infomration-Field is right shifted to make room for the new frequency. Cx*CALLSIGN# - Position Comment: This always expands to the one-of-9 pre-defined Mic-E position comments such as /off duty, /enroute, /in service, /returning, /committed, /special, /priority, /emergency, /custom 1. It will overwrite any previously existing Comment, otherwise it is appended to the end of the packet. Cxxxxxxxx...*CALLSIGN# - Free text comment: This is a variable length free field comment. It will replace any previous variable length comment if exists. Otherwise it will go to the RIGHT of any existing frequency field. It will completely overwrite/replace any previously existing position comment or other text to the right of the Frequency. MAP PLACEMENT: It is important to note that the LATITUDE (and maybe longitude) will be randomized in up and/or down to create a raster list on the map of the different DTMF users (until they provide their own position data. The raster offsets are chosen to make an appropriate scale LIST of these APRStt users on any APRS map display at the scale appropriate for that APRStt event or area. So this raster offset is a set-up variable for APRStt. For special events like Dayton where users are typically zoomed way in and there are lots of APRStt users the map offset for each call may be only 0.01 minute. So this is an APRStt sysop set-up option. Some APRStt engine may want this list to be to the East. Some may want it to the WEST, or North, or South or in any of the quadrants around the APRStt engine to avoid placing it on an area where other APRS stations may appear. So the base longitude of the list is also a sysop parameter. THis LIST location can be a different location from the location of the APRStt gateway symbol, because the APRStt symbol should be at the RF location of the APRStt decoder. Here is an example of how an EASTERN list would show on the map: WB4APR-12 KB3GLF-12 W3ADO-12 147.105-tt <== this is the location of the APRStt engine. AB3XYZ-12 KK3ABC-12 Notice how the APRStt FREQUENCY object itself is at the basic LAT/LONG but then the added users are placed above and/or below by a tenth of a minute (or about a 10th of a mile) for most normal areas. LATITUDE.yy DIGITS: How to build the latitude xx offsets is left up to the implementor, but new stations should not be added on top of other previous APRStt users unless their position is more than a time-out age. Again, this TIME-OUT age is a variable for SYSOP set-up depending on the particluar application. Normally, the default for APRS for this kind of inactivity time-out is 80 minutes. LONGITUDE.xx DIGITS: Similarly, for applicatiosn where there may be too many APRStt users to keep in one vertical list, the SYSOP may be able to choose to allow additional Longitude offsets if more than one vertical list is to appear on the map. MEMORY REQUIREMENTS: The APRStt processor has to have a memory bank for as many DTMF users that are active per 80 minutes. After a DTMF user has not been identified for more than an hour, then he should fade from the map like all other APRS users that are inactive. Lets just use 30 as the size of the memory for now as a starting point. The FIELDS that must be kept are: CALL,S,V,L,LO,T,P Where CALL is the 6 character callsign Where V is the user defined overlay character (0-9 or A-Z) Where L is the last LATITUDE digit you used for him where LO is the last LONGITUDE used for his placement Where T is a single byte Timer down counter Where P is a next-period digit (minutes to next TX) PROCESSING FLOW CHART: The following pseudo code describes the processing required for the APRStt process: NEW DTMF user report comes in... Scan above list of last N calls heard. Is old call? then: Set his Timer to 0 and Period to 1 and reuse his LAT if still available. If not, use next availble LAT Update the HHMMSS field. goto * TRANSMIT routine... Is NEW call? then: If room, add him to next available LAT slot. if not, Add him in place of the OLDEST call (biggest P) Re-use this oldest one's LAT digit Set his Timer to 0 and Period to 1. Update the HHMMSS field. goto * TRANSMIT routine... Contains additional info, posit, freq, comment, etc update packet, set timer to 0 and Period to 1 Update the HHMMSS field. goto * transmit routine TRANSMIT ROUTINE: Transmit the packet. Double the P period and set T = P. TIMING: Once every minute decrement the TIMER digit of all active objects. If any are 0, then TX them and DOUBLE their P and set their Timer to their new P. Notice this is the same * TRANSMIT ROUTINE above. It is what you do every minute. The combination of TIMER byte and PERIOD BYTE is what makes the APRStt engine Transmit new stations immediately, and then decay the Period longer and longer as time progresses. For a new station, the next packet will be a minute later, then 2 min later, then 4 min later, then 8 min later, then 16 min later, then 32 minutes later etc until P equals 64. The it is considered an inactive station LIST MAINTENANCE: Also every minute you check for any values of P that are greater than 64. These you stop transmitting AND preferably do a LATITUDE LIST clean up. If you forced the APRStt location to be at a latitude ending in .5, then here is a suggested algorithm. If the eliminated station's Latitude byte is greater than 5, then you scan the list for the largest Latitude Byte, and MOVE his data to this cleared position. If the eliminated station's byte is less than 5, then you scan for the lowest Latitude byte and move him to this vacated position. CLEAN LISTS: The idea is to keep the list closest to the APRStt's basic position so that the list is concise. As the popularity of this system grows, this algorithm may need to get smarter to handle more rows and columns. But by eliminating any calls that are older than 80 minutes, the list will usually be small. Or just keep it at 10 and then it simply always shows the 10 most recent users. But still if they are older than an hour, they should not be transmitted. The older ones remain with the global APRS system for 10 DAYS. Remember, once an OBJECT is transmitted, it will remain on all APRS maps in the world forever or until those clients timeout systems eliminate it. SO locally reusing a list position (latitude) will be piling calls on top of old calls in all clients. ----------------------------------------------------------------- APRStt GATEWAY IDENTIFICATION: ----------------------------------------------------------------- The above syntax is related to how the USER packets are generated. In addition, the APRStt has to put itself on the map with an additional packet every 10 minutes direct. This object should be a FREQUENCY object ending in some variation of "tt" if the APRStt gateway is operating on anything other than the 146.58 simplex frequency. The variations on the FFF.FFxyz object name should include "tt" somehow but also be chosen to be unique if it is desired for this gateway to be found uniquely on the APRS-IS. If the APRStt engine is on the suggested 146.58 frequency, then it can have an object name of "APRSttxyz" or something similar again to make it unique. FREQUENCY format if APRStt is on a unique frequency ;FFF.FFFyz*111111zDDMM.5_N\DDDMM.m_WrAPRStt Gateway ... STANDARD FORMAT IF APRStt is on the national input channel ;APRStt-NN*111111zDDMM.5_N\DDDMM.m_Wr146.58 MHz Rxxm ... Where FFF.FFFyz is the APRStt frequency and unique "yz" (or) Also FFF.FFxyz is the APRStt frequency and unique "xyz" Where the LAT/LONG is the location of the APRStt DTMF receiver Where "=" is the symbol for an APRStt engine Where free text follows. But this is also where a Tnnn tone or a Rxxm mile range may be placed. Additional text can be used, but nothing after 28 bytes will be seen on other D700 mobiles and nothing after 20 bytes will be seen by D7 HT users. For more detail on how these FREQUENCY OBJECTS are made and desired formats, see: http://www.aprs.org/localinfo.html The symbol for the APRStt engine can also be the same "r" symbol we use for other repeaters and frequency objects. TNC CONFIGURATION: In order to send the above OBJECT format over the air, a TNC needs to be connected to the APRStt engine's serial port. The TNC should be placed into CONVERSE mode, so that anything coming out the serial port will be immediately transmitted onto 144.39 in North America. Besides making sure the TNC is in CONVERSE mode, there are only 2 other settings required: MYCALL - The sysops or APRStt owners callsign UNPROTO APTvvv VIA WIDE1-1 Do not set any BText or other beacons. The APRStt engine's code will now be doing all of that. CHECKING THE SYSTEM: At any time, you can see how the APRS system is parsing your data by using the following URL: http://map.findu.com/FFF.FFF* or http://map.findu.com/APRStt* This will find your FFF.FFF APRStt object and the * will let you see if anyone else is using your same frequency (any where else in the world). You need to choose the 2 or 3 bytes on the end of your FFF.FFxyz to be unique in the world in order to have your repeater always show up at the same spot and not be replaced by someone else's identical FFF.FFF repeater. If we go with 146.58 simplex as a universal APRStt gateway frequency, the uniqueness of the xyz digits will become important. I suggest just sequential numbering starting with -01 through -99 and then A1 through ZZ. Tell your DTMF users to find themselves at the same URL: http://map.findu.com/CCCCCC* where CCCCCC is their callsign, and the * again is a wildcard to make it easier to see all of their APRS applications. Bob, WB4APR ------------------------------------------------------------------ Appendix A. Position Format Setup Variables ------------------------------------------------------------------ Note that most APRStt positions are referenced to DECIMAL MINUTES of latitude and longitude, since 1 decimal minute is about 1 mile and it is the standard for GPS data. So the math in APRStt is best done in DEGREES and DECIMAL minutes. Of the form DDMM.mm for latitude or DDDMM.mm for longitude. It is up to the author to decide how to use these internally. But for the formats below, all of the user data entry is in digits of MINUTES. Each of the 10 position formats has some setup parameters for the APRStt SYSOP to customize for his application. Here are the suggested variables for each format. The defaults will be for the 60 mile case, so that APRStt will work +/- 30 miles from any one location. B0_file = filename of file with 10 positions B1_Xorigin = DDD,MM B1_Yorigin = DD,MM B1_Xincrement = 10.0 B1_Yincrement = 10.0 B1_ambiguity = 3 digits (10 mile ambiguity) B2_Xorigin = DDD,MM B2_Yorigin = DD,MM B2_Xincrement = 1.0 B2_Yincrement = 1.0 B2_ambiguity = 2 digits (1 mile ambiguity) B3_Xorigin = DDD,MM B3_Yorigin = DD,MM B3_Xincrement = 0.1 B3_Yincrement = 0.1 B3_ambiguity = 1 digits (0.1 mile ambiguity) B4_Xorigin = DDD,MM B4_Yorigin = DD,MM B4_Xincrement = 0.01 B4_Yincrement = 0.01 B4_ambiguity = 0 (precise to 60 feet) 'B5zzzmm* Posit at bearing zzz range mm miles B5_Xorigin = DDD,MM B5_Yorigin = DD,MM B5_units = (Mi or Km) 'B6EEENNN* UTM Grid for SAR in Easting and Northing B6_Xorigin = DDD,MM B6_Yorigin = DD,MM 'B7RRRMMM* Road RRR at Milemark MMM B7_095 = filename for I-95 milemarks in this state B7_295 = filename for I295 milemarks in this state B7-RRR = filename for route RRR milemarks in this state B7_etc = and so on Actually, all milemarks in the country already exist in one APRS file that is well under 100k but by letting the sysop customise his area, he can add milemarks for any local road that has them. Remember, a straight road 100 miles long, only needs TWO points in this data file to allow precise positioning. So you only need points for significant changes in road direction. That's why these files may only a few points for each road in simplex range of this APRStt engine and it is very easy to set up. B8...* Table Interpolation This table is used for maping regular systems of numbers to geographic locations. A good example is the fleamarket spaces at Dayton. A table has been prepared that will map any 4 digit NNNN flea market space to a LAT/LONG. Another example would be street addresses. Each row in the table is a linear set of numbers with a start and ending point. The software interpolates any input NNNN to the correct location between the end points. Each row has 6 data entries as follows: N1, N2, A1D, A1M, L1D, L1M, A2D, A2M, L2D, L2M Where N1 is the starting number of a series Where N2 is the ending number of a series Where A1D, A1M is the LAtitude of the the start number Where L1D, L1M is the Longitude of the the start number Where A2D, A2M is the LAtitude for the end number Where L2D, L2M is the Longitude of the the end number For example, the Table for all 4000 flea market spaces at Dayton DAYTON-FLEA-N.TXT only has about 30 entries (one for each row in the fleamarket area)! see aprs.org/aprstt/DAYTON-FLEA-N.TXT Bob, Wb4APR