===[MAGBACK.TXT for MAGBACK v1.00]=====================-Doc v1.01 15.06.03-== Basics: MagBack is a tool that allows you to back up waypoints and routes from your Magellan GPS unit and restore them at a later date. All you need is a DOS capable PC and an appropriate Serial Cable that can be obtained from Magellan via www.magellangps.com. MagBack will run on any DOS from v3.0 and all flavours of Microsoft Windows and requires a Magellan GPS unit. Units from other manufacturers will not work as they do not support the necessary NMEA private messages as defined by Magellan Corp. Intended Users: This is a tool for professionals (that is PC AND GPS professionals!) only. Thus if you don't know what an IRQ Mask or the NMEA is, this software is not for you. Check the "Useful Links" section of this document to get an idea where to look for tools that might be of more help to you. Current Version: v1.00ß released 01.11.00 - First public beta. Please report bugs to DLange@bigfoot.com. Non-beta release is not very likely as I do not use my Magellan too much anymore. Has been replaced by a Garmin due to much better software support. [DL 15.06.03] Updates/More Info: Check www.daniel-lange.com . To report bugs email DLange@bigfoot.com. Also see the FAQ section on this. Legal Disclaimer: This software is FREEWARE. Thus you may use this software both privately and in a business without any other restrictions than leaving the authors copyright notice intact and always distributing software (MAGBACK.EXE and MAGBACK.INI) and documentation (MAGBACK.TXT) together. THERE ARE NO WARRANTIES ASSOCIATED WITH THIS SOFTWARE AND ITS DOCUMENTATION AT ALL, NEITHER IMPLICIT NOR EXPLICIT. IF THIS IS NOT ACCEPTABLE TO YOU, DO NOT USE THE SOFTWARE. YOU'RE ON YOUR OWN! A word of advice: So, if you read through here, you are a skilled PC and GPS professional and you know that anything you wreck with this software is your fault alone. That is why I'd ask you to read through ALL of this manual as this software is able to delete any file on your PC or network and delete all of your GPS waypoints, routes and track too. You're not scared? Let me remind you, that your GPS is a kind of navigation aid to you. But: This software is not too easy to use and I will definitely contain bugs. So be careful, check and double check your position information and navigation data. Never rely on any single tool, esp. not a GPS device! Contents of this manual ======================= 1. Introduction 2. System requirements 3. Using MagBack 4. Advanced Uses 5. Command and INI-File Reference A. FAQ B. Selected use cases C. Useful Links D. Acknowledgements 1. Introduction =============== MagBack has been written by me, Daniel Lange , during the XMAS break of '99 because I needed a simple way to back up and selectively restore information to/from my Magellan GPS. For units of other manufacturers there seemed to be a wealth of tools available but not too much for Magellan units. Well Magellan documented their use of NMEA private messages to communicate with their units publicly[2], so I sat down and wrote what I now call MagBack. I did not want to write what you can buy from Magellan or third party vendors because I don't need their moving map, SA watch, whatever functionality which then does not allow this software to run from a simple disk. I don't think harbour or backpacker Internet Cafes like me installing 20 Megs of software to load a few waypoints I forgot to my GPS. And remember to uninstall (what a word) it from you home PC before you take to the road, having two copies for ten minutes is most probably illegal. So, not with MagBack, it's Freeware. 2. System requirements ====================== You need any PC or device/software to properly emulate a 8088 processor or above and run any flavour of DOS from version 3.0. Any Windows 3.x, 9x, NT, 2000, Millennium etc. should work too. MagBack requires 64k of RAM for itself and something like 128k additionally for it's database functionality. See the "Advanced Uses" section for running in low memory conditions. You can make it run in 64k, if you desperately need too. 64k ought to be enough for everybody [BG] ;-). You need a free serial port with a properly set up IRQ line. Using COM1 or COM2 with a GPS as the single device attached and no drivers running set up to monitor the selected port works best. MagBack does support COM1-COM6 and any sensible IRQ up to IRQ15. 3. Using MagBack ================ MagBack relies on a file called MAGBACK.INI to reside in the same directory as MAGBACK.EXE. The INI-File contains numerous settings to widely customise MagBack's behaviour. If the INI File does not exist in that directory MagBack will advise you so and use it's build in presets that should work on COM ports the BIOS knows about (usually COM1 and COM2). Calling MagBack without any parameters or with "-?" (without the quotes, this is the last time, I'll say "without the quotes") will cause MagBack to give you a small reminder. MagBack command line switches will always override the settings in the INI file. Some settings cannot be set on the command line e.g. port set-ups due to the fact that they are very technical and wrong settings can make your computer crash. You will not want to set them "on the fly". The general format of MagBack's command line is: MAGBACK.EXE [-Parameters] [FILE.WPT] [Waypoint(s)|SCMD] specifies the main command that MagBack shall execute Valid Commands (CMD) are: bw - backup Magellan GPS Units' Waypoints br - backup Magellan GPS Units' Routes bt - backup Magellan GPS Units' Track Information ba - backup Waypoints, Routes and Track this is a short-cut for doing three repetitive commands with bw, br and finally bt r - restore information from file to Magellan GPS Unit i - display info about attached Magellan GPS Unit s - send special command SCMD to Magellan GPS Unit see the "Advanced Uses" section for more information on the special command [FILE.WPT] names the file that is the target for the backup or the source for a restore. You may use a drive and path here but the DOS version of MagBack will only support 8.3 filenames and short paths. If the file exists during a backup you will be asked whether to append to the file or overwrite it. Use -yes to force append. The file contains pure NMEA messages ($PMGNWPL...) as they are both sent and expected by/from your GPS. Blank lines and lines beginning with a semicolon (';') are ignored. See the "Advanced Uses" section for other types of lines supported (i.e. "Embedded Descriptions (.ed)"). [Waypoint(s)|SCMD] Waypoints are identified by their 6 letter names appended with the one character icon identifier. Waypoint names solely consist of UPPERCASE CHARACTERS and/or digits, the appended icon identifier is lowercase by definition. For the DOS version of MagBack replace all blanks with '_'. Escaping with "" is not supported. Example: HOME_1a is the waypoint 'HOME 1' with default filled circle icon ('a'). The icons as documented by Magellan for the Colortrak, Tracker, GPS 315/320 and MAP 410 are: a filled circle b box c red buoy d green buoy e anchor f rocks g red daymark h green daymark i bell j danger k diver down l fish m house n mark o car p tent q boat r food s fuel t tree Check the Magellan Specs. Document (see the "Useful links" section, [2]) for older units or figure it out from your GPS's screens. You may also specify a description from MAGBACK.DB to be searched for the restore function ('r') preceded by '#'. Example: #USA_Capitol_Hill will restore a Waypoint (e.g. WPT123) that has the description 'USA Capitol Hill'. Both waypoint names and descriptions support wildcards. An asterisk ('*') will match any amount of characters, a question mark ('?') must match exactly one character. See the "Advanced Uses" section for more info on the descriptions database (.db) and embedded descriptions (.ed). With the 's' command MagBack expects you to state the "special command" to be sent to the GPS here. See the "Advanced Uses" section for more details. [-Parameters] are all optional. You may use and combination of: -pCOMx : use COMx as defined in MAGBACK.INI. The default is COM1 and MagBack will obtain the port settings for BIOS supported ports (usually COM1 and COM2, sometimes COM1-4) from the BIOS. You can superceed these values in the INI- file ([COMx]BaseAdr, IRQ, IntVect, IntMask1 and IntMask2). You can set the INI directive [General]Port=COMx to make MagBack use this port. -vx : Verbose mode x. -v0 will make MagBack output virtually nothing. -v1 is the default. -v2 will inform you about some command line options active (e.g. the .db file) and will notify you of wrong NMEA checksums. -v3 will output the GPS info as in the "i" command during other commands as well. It will also tell you some internal stages MagBack successfully passes while initialising. Last it'll show you the line with the wrong NMEA checksum as from -v2. At -v4 you will also be notified of wrong messages received from the GPS. -v5 will inform you on when Transfer Mode ans Handshake are set or unset and which Matches lead to preparing a waypoint/route etc. for uploading. When en error occurs that requires MagBack to end prematurely you'll see a message similar to "Termination Code: xxx-yyy/zzz". Copy this message to your email when mail in an error description. -v6 will inform you on non-fatal timeouts and tell you of any matches the .db or the .ed have against the currently processed waypoint. The mess starts around here. -v7 will tell you any detail on the checksums whether valid or not. It'll also tell you of WPTs etc. NOT matched in .db or .ed. Last it will tell you which lines from input file were skipped. -v8 will show you all messages sent or received in their full NMEA beauty. They are prefixed with "GPSSend" or "GPSReceive" respectively. At -v9 every byte received on the COM port is output to the screen directly. Higher modes obviously include output of all lower modes. The output will be in the format "Vx-y:Message" with x being the level of verbosity you choose and y being the level from which the message is available. Thus y<=x. At level 9 the raw COM port bytes are sent to the screen. Example: V5-4:Waypoint Message with Checksum Error received. -f : MagBack will read descriptions to go with your waypoints and routes from FILE.DB (default is MAGBACK.DB). The file you specify will be searched for in the current directory, then in the directory where MAGBACK.EXE is located (Home directory). ".ED" will force MagBack to read "Embedded Descriptions" from the Waypoint/Route File ("FILE.WPT"). Check the "Advanced Uses" section for more on Databases and ED's. -sSECTIONNAME : Databases are devided into sections just as the INI-file is. SECTIONNAME is the section that MagBack will read into memory and use for analysing descriptions given on the command line for the restore ("r") command. The default section name is "MAGBACK" in case you neither override it on the command line or in the INI-file. The SECTIONNAME is case-insensitive. It is not matched with wildcards! -yes : MagBack will assume YES to all queries except when asking for permission to overwrite a file. It will assume APPEND then. WARNING: Using this switch may result in loss of data either on your hard disk or in your GPS or other unwanted behaviour. Know what you do! -hs[=on|=off] : The Magellan Handshake protocol is a proprietary extension to the NMEA set of messages. It will allow some error checking so that backup or restore messages are retransmitted if they failed to reach the other end properly. As you may well know, the NMEA messages have a simple checksum to check for integrity but while this does allow to detect most errors the Magellan protocol will allow to request resents and detect messages missing in a transmitted batch (i.e. of WPTs). -tm[=on|=off] : The Transfer Mode will put the GPS into a mode so that it will put more processing power on transmitting Waypoints or other non-missing-critical NMEA messages and omit the navigation "fuss" we don't need for MagBack operation. Transfer Mode will also cause the screen to display a notification message instead of the standard screens. MagBack will try to put your GPS back to GPS mode after transfers have finished and even try to do so in case of an error. If something seriously went wrong (e.g. you removed the cable to the GPS before MagBack was finished) power cycle your GPS to end Transfer Mode. -timeout=x.y : Set the time MagBack waits before it will declare failure to receive a GPS message it waited for to x.y seconds. Valid: 0.0 (=infinite) to 3600.0; Default: 10.0 -retries=x : Allow MagBack to retry x times to send a message or receive a valid response. You must set retries to a non-zero value if you use MagBack with your GPS exposed to satellite signals. The maximum time MagBack will keep retrying is timeout*retries seconds. Valid: 0 .. 1000; Default: 0 Now after you've read through all of this attach your Magellan GPS to COM1 and issue "MagBack bw WAYPOINT.WPT" to do a first backup of your GPS's waypoints. Then type "MagBack br ROUTES.WPT" to save the routes. Copy *.WPT to a disk and store it safely away. If you use COM2 for the backup commands above, either insert "-pCOM2" to each or edit the MAGBACK.INI to make MagBack use COM2 by default. Other Examples: MagBack i -pCOM3 Show information about the attached GPS on port COM3. To get rid of the -pCOMx, set your default in MAGBACK.INI. MagBack ba BACKUP00.WPT Backup all waypoints, routes and the track from your GPS at COM1. Watch the progress: One "#" means 10 messages received. Be patient. MagBack r BACKUP00.WPT FISH* *l Restore all waypoints from BACKUP00.WPT which name starts with "FISH" and/or that have been assigned the fish icon. The command will also restore all routes that have names beginning with "FISH". Note that most Magellan GPS's won't allow routes to be named ( and thus name them "00","01"..). MagBack r BACKUP00.WPT MOB??? MOB MOB_* Restore all waypoints and/or routes from BACKUP00.WPT that match at least on of the following conditions: 1) The name starts with "MOB" and is exactly 6 characters long. 2) The name is exactly "MOB". 3) The name starts with "MOB " (note the blank) and can, but need not, have anything appended to that. MagBack r -hs -tm -retries=5 BACKUP00.WPT #*fish* Restore all waypoints and/or routes are described in MAGBACK.DB, Section "MAGBACK" in the current directory or MagBack's home directory and contain "fish" (case does not matter). Use transfer mode and ensure the transfer is free from error through the handshaking protocol. Allow max. 5 retries. See the following section for more on descriptions and the other options available with MagBack. 4. Advanced Uses ================ This section will help you to make the most out of MagBack e.g. using the database system or using special commands to interact directly with your GPS. Contents ======== 4.1 Interpreting the 'i' command response 4.2 Using the Descriptions Database and Embedded Descriptions 4.3 Screen Messages in .WPT files 4.4 Send Special ('s') command 4.1 Interpreting the 'i' command response ========================================= GPS INFORMATION for UNIT on COM1: Magellan Unit Type ID: 19 Unit Name: COLORTRAK Software Revision Level: REV 2.05 Installed Database(s): (none) Time to answer: 0.250s The Unit Type ID is unique to the Model and the "Unit Name" is actually a textual description of the ID. See the table below. The installed databases are only available on devices with built-in or user uploadable maps/ point-of-interest list. These have nothing to do with MagBack's waypoint backup files and the .db databases that may accompany waypoint files. The "Time to answer" gives you indication of how long it took MagBack to contact your GPS on the initial 'VERSION'-Command. This depends on your GPS, it's current processor load, the baud rate used between PC and GPS and - to a minor extent - from the speed of your PC. You can use this time as an indication what the -timeout time should be (5 is a good factor). From [2] you'll get the following table: PID Unit Name PID Unit Name 001 SkyBlazer 002 Skyblazer XL 003 Skyblazer LT MAP 004 Skystar -- 2 channel 005 Meridian XL 006 GSC­100 007 Trailblazer XL 008 Trailblazer XL -- Arabic 009 Patriot 010 NAV 1200 011 GPS 2000 012 GPS 2000 -- OSGB 013 GPS 3000 014 GPS 4000 015 GPS 3000XL 016 GPS 2000XL 017 DLX 10 018 NAV 6000 019 Colortrak 020 Skystar -- 2 channel 021 GPS 2000XL -- with data 022 Skystar -- 12 channel 023 Tracker 024 GPS 315/320 025 MAP 410 4.2 Using the Descriptions Database and Embedded Descriptions ============================================================= MagBack supports to type of files: 1) NMEA message files that contain waypoints, route messages etc. (.WPT) 2) Database files that contain descriptions for waypoints or routes (.DB) The latter looks much like a Windoze INI-File, i.e. it consists of "sections" that are enclosed by square brackets ("[..]") and entries that separate a GPS waypoint/route id and its description (=the payload) with an equal sign. These databases can contain anything you can put into 80 characters to describe a waypoint, route etc. So a part of the database file may look like this: [GERMANY] DEAACH=AACHEN,MERZBRUECK,A3C:AAH,ICAO:EDCM DEAHLH=AHLHORN (GER-AFB),ICAO:EDNA DEALTB=ALTENBURG,A3C:AOC DEALTE=ALTENSTADT/SCHONGAN,ICAO:EDPL ... The accompanying .WPT file may look similar to this: $PMGNWPL,5081.667,N,00618.333,E,0000000,M,DEAACH,,a*59 $PMGNWPL,5288.333,N,00823.333,E,0000000,M,DEAHLH,,a*56 $PMGNWPL,5098.333,N,01243.333,E,0000000,M,DEALTB,,a*4E $PMGNWPL,4783.333,N,01086.667,E,0000000,M,DEALTE,,a*4A ... In the above example the database entries do not contain an icon designator. Thus these entries will match any WPL message with any icon or any RTE message. If the entry "DEAACH=AACHEN,MERZ..." were changed to "DEAACHa=AACHEN,MERZ..." it would only match the single waypoint with ID="DEAACH" and icon="a". This two-file approach has numerous advantages: 1) You only need to specify descriptions for you favourite waypoints once and can still do frequent backups with your improved position fixes. The .db file will never by written to by MagBack itself (unless you overwrite it with a NMEA output file by accident.) 2) You can have multiple .DB files for one set of data in a .WPT file e.g. depending on the specific usage. You could e.g. break up the A3C and ICAO descriptions in the above example to have one .DB file with A3C names and one with ICAO airport names. 3) You can maintain one central .DB file for your collection of waypoints and still have multiple .WPT files with your waypoints, routes and track e.g. one for every holiday. MagBack will only load one section from the database so you can use this feature to structure large collections. Waypoint names need only be unique within a section so that you can replace the waypoints "FISH1", "FISH2" etc. in your GPS every time with the right locations depending what waters you want to fish in. So you can use "MAGBACK r -fFISHING.DB -sLAKE_TAHOE ALL_TH.WPT #*" to upload all waypoints that are listed in the section [LAKE TAHOE] (the '_' is converted to a blank) in FISHING.DB and exist in ALL_TH.WPT (right, no blanks in DOS filenames). The "#*" translates to "any description" thus the waypoint must be listed in FISHING.DB to have a description at all. "*" would - BTW - be interpreted as "any waypoint" or - more precisely - a waypoint which name matches "anything". In smaller files you may not need to create a structure. Just use the default section name "MAGBACK" as your single section. BTW: The default .DB file that MagBack looks for is "MAGBACK.DB". You can change that in the INI-file. MagBack assigns a specific amount of memory to its internal database engine. By default it will be able to load "Description Databases" of around 1000 entries. This limit is artificial and set because it seems to be a good trade-off between speed (=more entries take longer to initialise) and "sensible use". In addition to that it will allow MagBack to run in around 128kB of free memory. If you have less (e.g. on a device only emulating a 808x PC) you can set the environment variable "MagBackDBLines" to the amount of .DB entries you need to process in one go (i.e. maximum size of a section). The minimum value is "50" as this amount of memory is also required for INI-file processing. You can also set "MagBackDBLines=AUTO" to have MagBack allocate all memory it can to the database engine. In files you prepare to give away or you'll change very infrequently, you can also use "Embedded Descriptions". Processing these is forced by putting "-f.ED" on the command line. You can also set the INI-Entry [General] DBName=.ED to make processing embedded descriptions your default selection. An embedded description is a line that looks like "#EDv1=..." and is located in the .WPT file right above the waypoint, route or set of waypoints and routes it describes. The above example would look like this: #EDv1=GERMANY AACHEN,MERZBRUCK,A3C:AAH,ICAO:EDCM $PMGNWPL,5081.667,N,00618.333,E,0000000,M,DEAACH,,a*59 #EDv1=GERMANY AHLHORN (GER-AFB),ICAO:EDNA $PMGNWPL,5288.333,N,00823.333,E,0000000,M,DEAHLH,,a*56 #EDv1=GERMANY ALTENBURG,A3C:AOC $PMGNWPL,5098.333,N,01243.333,E,0000000,M,DEALTB,,a*4E #EDv1=GERMANY ALTENSTADT/SCHONGAN,ICAO:EDPL $PMGNWPL,4783.333,N,01086.667,E,0000000,M,DEALTE,,a*4A ... There are three advantages to using embedded descriptions: 1) You only have one file. 2) Reading embedded descriptions is at least some 100 times faster than searching the .DB for matches. 3) You can upload groups of messages by putting a single embedded description on the line right above the group. I.e. the embedded description spans multiple lines in the .WPT file. This requires you to put an empty embedded description ("#EDv1=") on the line after the pack (or some other .ED that will be valid for the NMEA message(s) to follow it. Example: #EDv1=GERMANY ALL AIRPORTS ... $PMGNWPL,5098.333,N,01243.333,E,0000000,M,DEALTB,,a*4E $PMGNWPL,4783.333,N,01086.667,E,0000000,M,DEALTE,,a*4A ... #EDv1= ... The downsides are: 1) You can easily overwrite a .WPT file with embedded descriptions with a new backup from you GPS. This will make you loose all your .ED's as your GPS won't know about them. Be very careful. 2) It's rather inconvenient to copy .ED's to newer .WPT files all the time. As I said above, .ED's are mostly for static, exchange type files. You can download a large set of demo waypoints from MagBack's homepage[1]. These are not suitable for navigation but will provide good examples of how waypoints work with associated .db file entries and how to build self contained .ed files. 4.3 Screen Messages in .WPT files ================================= You can make MagBack output a message when it processes a .WPT file through putting a line like "!" anywhere in the file. This will allow you to tell others something about your data file every time MagBack parses the line starting with an exclamation mark during an upload. Magback will output something like "MSG: " to the screen. 4.4 Send Special ('s') command ============================== As you know NMEA messages are trailed by checksums that can be quite boring to compute if you need to speak to your GPS directly. Now MagBack is a tool for pros, so I guess you regularly delete waypoints from your terminal programme... This will require you to construct a message like: $PMGNDWP,,*hh with hh being the NMEA 0183 checksum v2.10. E.g. to delete the waypoint "WPONEa" you need to issue "$PMGNDWP,WPONE,a*75". MagBack facilitates this by calculating the checksum for you: Just type "MagBack s $PMGNDWP,WPONE,a". Remember that NMEA Messages are in ALL UPPERCASE except for Magellan's icons which are always lowercase. If the SCMD given to the 's' command does not start with a dollar sign MagBack assumes you want to issue a $PMGNCMD and prefixes that (and a comma) to what you typed as SCMD. E.g. to delete the track from your GPS you need to type: "MagBack s DELETE,TRACK" and MagBack will construct the message "$PMGNCMD,DELETE,TRACK*08" and send this to your GPS. Be very careful with this as "MagBack s DELETE,ALL" will purge your GPS with no further questioning! Magellan defines the following sub-types of $PMGNCMD to be valid: Command Expected Response Description ALMANAC PMGNALM Send Almanac Data DELETE Empties the data buffer specified in the next field: WAYPOINTS - deletes all user waypoints ROUTES - deletes all user routes TRACK - deletes all points in the track buffer FIX - deletes all saved fixes ALL - deletes all of the above AIRCRAFT - deletes all aircraft characteristics EPHEMERIS GSV Send Ephemeris data FIX GGA Begin sending fix information until a STOP command is received ROUTE PMGNRTE Send Route messages. Better use "MagBack br". STOP Discontinue sending stream data at completion of current block. TRACK PMGNTRK Send Track messages. Better use "MagBack bt". UNABLE Sent by the unit when a previous command cannot be complied with. VERSION PMGNVER Send a string giving product and software version information. Better use "MagBack i". WAYPOINT WPL or PMGNWPL Send NMEA Way Point Messages. Better use "MagBack bw". CHECKLIST PMGNLST Send aircraft check list data. FLIGHTPLAN PMGNPLN Send aircraft flight plan data. AIRCRAFT PMGNACC Send aircraft characteristic data. MPHDR PMGNMPH Send map header information MPUPLOAD Put unit into map upload mode PIHDR PMGNPIH Send POI header information PIUPLOAD Put unit into POI upload mode MESSAGES PMGNMSG Send email messages ADDRESSES PMGNADR Send addresses from address book (quoted from Magellan's Data Transmission Protocol Specification Rev1.0) MagBack allows you to use multiple SCMDs within on 's' command. Just separate them with blanks. Blanks inside the SCMDs (e.g. in a waypoint name) need to be replaced - as always - with '_'. 5. Command and INI-File Reference ================================= Nearly all parameters that can be set on the command line also have a corresponding INI-file setting in the [GENERAL] section: Command line INI-file -v1 Verbose=1 -pCOM1 Port=COM1 -retries=10 Retries=0 -timeout=20.0 Timeout=20.0 -hs=on Handshake=ON -tm=off Transfermode=OFF -fMYDB.DB DBName=MYDB.DB -sSECTION1 DBSection=SECTION1 If you want to answer "yes" or "append" to all prompts automatically, e.g. in batch files you'll have to specify "-yes" on the command line. There is no INI setting for this. "-yes" will primarily result in: 1) Automatic appends to existing files on backups. 2) Mass uploads if you do not specify a pattern on the command line but a section from a .DB file 3) No waiting for a keypress between 's' SCMDs. Other settings are not changed very frequently so they have no corresponding command line parameter: Hash defines after how many successfully sent or received NMEA messages an additional hash mark '#' shall be output Valid: 0 (=off) to 5000; Default: 10 e.g. Hash=10 (HashFactor*Hash) Lines read during 'r' command in Parse mode will output an additional '.' to console. Valid: 0 (=off) to 5000; Default: 10 e.g. HashFactor=10 MagBack has the ability to prevent a user to break out of the application with Ctrl-C, Ctrl-Break or Alt-Ctrl-Del. This can be useful depending on the usage scenario (see the "Selected Use Cases" section). DisableCtrlC defines whether the application will allow DOS to break into it's execution when the user presses Ctrl-C Valid: ON, OFF; Default: ON e.g. DisableCtrlC=ON DisableBreak defines whether the application will allow DOS to break into it's execution when the user presses Ctrl-Break Valid: ON, OFF; Default: ON e.g. DisableBreak=ON DisableBoot defines whether the application will allow DOS to reset the machine when the user presses Alt-Ctrl-Del Valid: ON, OFF; Default: OFF e.g. DisableBoot=OFF In case you disable Ctrl-C and/or Ctrl-Break checking (default), you can abort any lengthy activity by pressing Ctrl-Esc. This will allow MagBack to end the current activity, get the GPS out of Handshake and Transfer Mode, if necessary, and drop you back to the command prompt in a safe fashion. Pressing Ctrl-C or Ctrl-Break when you have DisableCtrlC=OFF or DisableBreak=OFF will leave breaking out of MagBack to the OS (like it'll do with any other application). While this works 99% of the time it will also leave half-way done with .WPT files on the disk and your GPS in an undefined state. For all supported COM ports (COM1-COM6) you'll find a readily prepared [COMx] section in the distributed MAGBACK.INI file. Here you can set the DTE speed that MagBack uses to communicate with your GPS. This setting needs to correspond with the set-up of your GPS. Experts can also configure COM ports that are not supported by the BIOS and/or do not use default settings. Check the INI-file for more details on the options available. There are two special debug parameters you should know about: "-DEBUG=VERSION" will make MagBack output something like this: Output on STDOUT Description $VV=00100 Version of the following information......MMMmm $MV=00100 Minimum version of the parser to read the following information....................MMMmm $APP=MAGBACK Name of the Application................Char(80) $OS=DOS_PURE Operating System.......................Char(80) $VERSION=00100-B Version of the Application.....MMMmm[-x][-LANG] with x='A':alpha, 'B':beta, 'C':gamma, 'R':release, 'S':special (not required to be present, hence [-x]) LANG denotes the Language of the application, e.g. EN for English or ENUK for UK English. MagBack is currently not available localized thus it will omit the -LANG part. $EDID=EDV1= Preferred Embedded Description Prefix..Char(40) There can be multiple blocks like the one above differing at least in $MV. $VV will be increased to reflect new information available. So the algorithm is: Check that $MV is <= your parser's version and that $VV is high enough to contain the info you need. Keep the information from the highest $VV that you are able to read. Skip any $VARIABLE that you do not know silently. Stop parsing only at the end of the output stream. Refuse to run, if you did not find any $MV <= your parser's version! $OS at $VV=0100 can be DOS_PURE, DOS_LFN, WIN32, WINNT and a few others. You can expect MagBack to be fully compatible on command-line level through versions $VERSION=MMMm0 to $VERSION=MMMm9. The basic command line parsing will be very similar for any given unique major version ($VERSION=MMM). "-DEBUG=SVC" will Skip the Version Check during MagBack initialisation. Thus it will not notice whether there is a GPS attached and happily show you the outcome of some complex command you constructed. Unplug your GPS and try things out with this switch set to not risk data in your GPS. Use -v8 for the full experience and do not use -tm (no GPS attached) or -hs (requires GPS to answer the handshake). MagBack recognises the name of it's executable and tries to find a corresponding INI-File. So MAGBACK.EXE will look for MAGBACK.INI (the default) while MB.EXE will look for MB.INI. The default .db name will also be changed to MB.DB. The default section name will nevertheless always be "MAGBACK". A. FAQ ====== Q: MagBack does stupid things, but I dunno why... A: Rename MAGBACK.INI to anything.xxx so MagBack won't find it anymore. This makes MagBack use it's default settings. Now try your command again with the GPS device on COM1. Q: I have a complex restore (r) command and would like to test what it does before messing up my GPS memory with it. Can this be done? A: Detach your GPS from the serial cable. Add -v8 and -debug=svc in your command line, so it looks similar to: MagBack -v8 -debug=svc r myfile.mb #*Germany*DN?? #WPT_0? ... -debug=svc will Skip the Version Command (hence svc) which helps MagBack identify the GPS unit it talks to. -v8 sets a verbose level high enough so you know what waypoints or routes would be uploaded. Do not use -tm (transfer mode) or -hs (hand shake mode) as these require GPS interaction. Q: MagBack times out on backup commands while it is exposed to GPS satellites. What can I do? A: The reception of the signal and updating the display have highest priority with your GPS. Even NMEA position output is more important than sending you the waypoints, routes etc. So you can: 1) Remove the GPS from GPS satellite exposition. 2) Use the transfer mode (-tm) to make handling your requests the top priority. 3) Use handshake mode (-hs) and high -timeout and -retries values so MagBack won't give up to easily. -timeout=20 and -retries=50 should do the job. Then get a coffee. Q: Is there a LFN or Win32 Version? Do you support *nix? Do you intend to do so? A: Not yet (at the time of this writing, check my web pages). No. If there is sufficient demand, why not? Q: I found a bug. What do I do? A: Write an email to DLange@bigfoot.com and describe the error. Attach a screen dumb created with -v8 or -v9 and files that 'cause the error to occur. I'll try to fix it. Q: Why are Embedded Descriptions prefixed with #EDv1= ? A: The hash mark makes a GPS ignore this line altogether if you are ever in the need to upload your .WPT file with a standard terminal programme because the machine you're working with won't run MagBack. The version identifier ("v1") allows me to make more advanced embedded descriptions later and still be "downwards compatible". Currently .ED's don't have any semantics, they are dumb text. If I ever need to change that, it'll be called "#EDv2" or so. Q: Can I compress the MagBack.exe file to save space? A: Yes, you can. UPX, see [4], works well and squeezes ~60% of hot air out of MagBack.exe. MagBack comes uncompressed so you can better check for the absence of virii. Please do not spread compressed versions of MagBack around. B. Selected use cases ===================== Contents ======== B.1 On the road B.2 Adventure Tour / Cross Country B.3 Synchronising waypoints/routes between multiple GPS devices B.1 On the road =============== Format yourself a floppy with DOS system files on it. Put a small DOS text editor and all MagBack files on it. Use 'bw' (and when required 'br') with a few rotating files whenever you read your mail in an internet cafe. If you like MagBack drop me a line at DLange@bigfoot.com. Send your WPT/RTE file(s) home every now and then too. You may loose your disk. B.2 Adventure Tour / Cross Country ================================== If you want people to go legs, write a combined WPT and RTE file for each stage and have a laptop with MagBack 'r' running in an endless batch looping when somebody attaches a GPS and hits a key. Clear the memory where required with the 's' command (e.g. "s DELETE,ROUTES") - obviously be careful with this. You can do personalisation using a fake WPT in the GPS unique to the individual team/member. Be sure to re-upload a new or the same unique WPT after a gross deletion of waypoints. You can also do automatic 'bw' commands if people are required to document that they successfully found landmarks with a GPS waypoint entry. You can also use 'bt' if you want people to sleep a few hours or they need to have proper lunch ;-). Check the INI-file whether you want to set DisableCtrlC, DisableBreak and DisableBoot to ON. "Ctrl-Esc" will usually get the user of MagBack unless all three INI-Settings above are set to "OFF" (which means "Ctrl-Break" will be available to quit MagBack). So the application is neither water-proof nor user-safe (...you know, what I wanted to write, don't you?) by itself. There are endless possibilities but do make sure that everything will work without a technician and that people have a backup if the laptop or a GPS breaks. B.3 Synchronising waypoints/routes between multiple GPS devices =============================================================== First: Your GPS identifies waypoints by name and icon ("WPT123a") thus it will replace WPT123a in the device with a new WPT123a sent from MagBack no matter whether you wanted that to happen or not. Routes are identified by name (often only a number, e.g. "10") and a ColorTrak will drop routes not named within the valid "number space" without any comment (i.e. no "UNABLE" message). So, you'll have to have some means to make sure that one GPS will not accidentally overwrite the other GPS's waypoints or routes that happen to have the same name (and icon). You could - for example - agree on prefixing your waypoints with some fixed character or number. Then do "MagBack bw/br GPSx.WPT" on all x devices. "Copy GPS1.WPT+GPS2.WPT+... GPSALL.WPT" will combine the files. Now you can restore this to all GPSs ("MagBack r GPSALL.WPT"). The GPS devices will set all timestamps to the current date and time on waypoints they receive through the wire. If you want them to be all the same you can construct yourself a cable with multiple GPS plugs on it. Use MagBack with "-debug=svc" then to make it dumb upload the GPSALL.WPT file. A word of warning: Do not draw to much current from your COM port. Use a galvanic de-coupler with separate power supply to drive multiple units. C. Useful Links =============== [1]MagBack Homepage.......................................www.daniel-lange.com [2]Magellan Corp...........................................www.magellangps.com The document you need is called Data Transmission Protocol Specification for Magellan Products P/N 21-00091-000 (Rev1.0 from 16.08.99 or newer) [3]Jack & Joes GPS Info.......................................joe.mehaffey.com [4]Ultimate Packer for Exe's....http://wildsau.idv.uni-linz.ac.at/mfx/upx.html D. Acknowledgements =================== Magellan, Microsoft, Windows and many other words mentioned in this document are Trademarks, Service Marks or in other ways copyrighted by their respective owners. The absense of TM, SM, (C) or some other tag does not mean the word/term is free from third party rights. All owner rights are acknowledged. The author of MagBack is in no way affiliated with Magellan Corp. other than being a happy user of their products. Neither is Magellan Corp. in any way affiliated with this software. They most probably don't know it exists. So don't ask them for support on MagBack. Thanks go out to the folks at SWAG (SourceWare Archival Group), you were great. ===[END OF FILE MAGBACK.TXT]===========================-DLange@bigfoot.com-==