PsiGar 2.5
----------


PsiGar is a shareware program for owners of Garmin GPS45 GPS receivers.
I have no reports of problems from users with the 38,40,65 and 75 models.
It will probably work with other Garmin receivers but I can't verify this.
There have been some problems with a GPS90, but all the others work ok so far.
The problems seem to be with the built in waypoints making route editing
impossible.


If you like this program and/or use it for more than 30 days you are
required to register it. The registration details are given below.


Please read this entire document before using the program.

PsiGar allows you to save Waypoints, Routes, Track Logs and Almanac information
onto your Psion series 3a.

The waypoint file can be converted to database compatible file and edited or
added to as any other database file. 
The altered file can then be sent back to the GPS receiver.

The registered version also allows you to send  Routes, Track Logs and 
Almanac data to the receiver. Of these file types only routes and track
logs can be edited.


NEW to version 2.5

The Psiway addon module allows you to enter waypoints in a more convenient way.
You can use the Psion to create a waypoint averaged out over a number of 
readings, create a waypoint using the Psion as an external keyboard for the
GPS and enter waypoints manually and either send them direct to the GPS or
save them in a waypoint file.
The Psiway addon module also includes Wayedit which supports the direct editing
of ".way" files without having to create database files first.
You can now enter OSGB grid references directly in Psiway.

When viewing a waypoint file with Psiway you can also view
a waypoint in OSGB grid references by selection "OSGB Grid View". You can now
edit a waypoint using OSGB Grid references. 



This software is under constant development so it is quite possible that there
could be bugs present in the software.
In particular the Psiway module could easily contain bugs as it has had very
limited testing.
The OSGB bits of Psiway are not yet complete and can crash if you enter invalid
numbers, I'm not sure what the valid limits are so I have not yet been able to
put constraints into the program

Please read the disclaimer at the end of this document before using the 
software.

Please feel free to contact me with any suggestions or queries, preferably at
the email address below.




Installation.

Firstly if you are updating from an earlier version you may delete the file 
"garhead.dbf" from the "m:\opd" directory.
I have changed waypoint database files to use the extention ".wbf" rather than
".dbf" to make them easier to recognise.
In version 2.0 and 2.1 Psirbf.als and psitbf.als were incorrectly named
psirte.als and psitrk.als. You can rename these files or not as you wish.


copy PSIGAR25.OPA to your \APP directory
copy PSIWAY.RSC to the same \APP directory as PSIGAR25.OPA
copy WAYHEAD.WBF to any \OPD directory 
copy RTEHEAD.RBF to any \OPD directory
copy TRKHEAD.TBF to any \OPD directory
     (You may need to make this directory first)
PSIGAR25.OPA is the main program file.
PSIWAY.RSC is the PsiWay addon module.
WAYHEAD.WBF is a header file which must be present to edit data files.
RTEHEAD.RBF is a header file which must be present to edit routes.
TRKHEAD.TBF is a header file which must be present to edit track logs

Optional.
copy PSIRBF.ALS to your \APP directory
copy PSITBF.ALS to your \APP directory
copy PSIWBF.ALS to your \APP directory
These are alias files using the data application to point directly to
the route, track and waypoint files in the psigar directory. This speeds
up viewing PsiGar database files as you don't have to change directory to
access them.


Install PSIGAR using <PSION> <I> in the usual way

Optional.
Install PSIRBF.ALS, PSITBF.ALS and PSIWBF.ALS using <PSION><I>.

You will need a Psion serial link lead and connection lead to attach to the 
port on the GPS receiver. The relevant lead with bare wires is available from
most Garmin dealers. You will probably have to make up the Psion end to 
connect to the serial link yourself.

For a GPS 38,40,45 or 75 the wiring required is
For a 25 way male Dtype as used with the PC 3Link the wires are
pin 2 brown (Data out from GPS)
pin 3 white (Data in to GPS)
pin 7 black (Ground)
For a 9 way male Dtype as used with the PC 3Link the wires are
pin 3 brown (Data out from GPS)
pin 2 white (Data in to GPS)
pin 5 black (Ground)

If using a Psion modem link rather than a PC link you reverse the wiring
for pins 2 an 3 for both 9 and 25 pin dtypes.

The red wire is the external power supply connection and is not needed.
If using an external power supply the black wire is the earth for this as well.
Some dealers will supply a ready made lead ending with a 3Link mini din plug
though this is more expensive, roughly 40.

For  a GPS 120 using a Garmin bare wire power data cable
GPS 120        25 pin dtype connector
Blue      	pin 2
Brown          	pin 3
Black          	pin 7

You can make the cable up using a mini din plug to connect to the podule on
the serial link lead but they can be very difficult to solder due to the
number of small pins very close together.



Operation

The program is menu driven and easy to understand.


First setup your GPS45 for GARMIN / GARMIN  HOST mode on the I/O setup menu.
Make sure the lead is connected and the GPS left on.
Make sure the Psion serial link is turned OFF on the system screen.

Run PsiGar.

Select menu GARMIN > PSION and any of the options.

ALL sends almanac info, routes, track logs and waypoints to the Psion.
The other options send the indicated items only.

The following default filenames are used:

almanac info        M:\PSIGAR\PSIGAR.ALM
routes              M:\PSIGAR\PSIGAR.RTE
track logs          M:\PSIGAR\PSIGAR.TRK
waypoints           M:\PSIGAR\PSIGAR.WAY
Waypoint database   M:\PSIGAR\PSIGAR.WBF
Routes database     M:\PSIGAR\PSIGAR.RBF
Track Log Database  M:\PSIGAR\PSIGAR.TBF

Psiway waypoints    M:\PSIGAR\PSIWAY.WAY


If you now select PSION > GARMIN you can send any or all of these files back
to the GPS receiver. (Only waypoints can be sent back in the unregistered 
version).

The action here is essentially additive for routes, waypoints and track logs.

Sending an almanac overwrites the current one. I can't think why you would want
to do this unless your batteries had died and you had lost all your stored
data.

Sending a route file updates the routes in the file only, other routes are 
not touched. NOTE If the route you send has names corresponding to existing
waypoints these waypoints will be updated if necessary to match the ones in 
the route. Any waypoints in the route not currently in the waypoint list in
the receiver will be added to the waypoint list.

Sending track logs updates the track log already present by adding more points.
Note a line will be drawn from the last existing point to the first loaded 
point when viewed on the map screen.
I have found it useful to save all my track logs as separate files so that 
I can retrace any route simply by loading the appropriate log. Having only one
route present at any time gives a much clearer display on the map. It also
allows you to use a more frequent update interval on the mapping screen as
you can have the full number of points available each time.

Sending waypoints updates any existing waypoints with the same names 
and adds any that do not exist. Any existing waypoints not in the file 
will not be touched.


You can use the GARMIN Waypoint> DATABASE option under the FILE CONVERSION 
menu to convert a Garmin waypoint file to a file that can be edited using 
the 3a's data program.
With PsiGar version 2 I would recommend using the Wayedit option in the 
PsiWay module instead as it allows for easier text entry with a degree
of error checking and also saves the need of converting to database files
and back again after editing.

This file will default to M:\PSIGAR\PSIGAR.WBF.
When entering or altering information using the data program you must stick 
to the following guidelines. 

1: The name field should be a max of 6 letters.
2: Latitude should be -89.99998 to 89.99998 degrees
   positive value for north, negative for south.
3: Longitude should be -179.99998 to 179.99998 degrees
   positive values for east negative for west.
   
4: Latitude and longitude values should be for a WGS84 map datum
   as this is how the Garmin Protocol outputs its waypoints.
   Also if you want to compare latitude and longitude values with those
   on the gps to check that all is ok, the gps must be set to
   position format hddd.ddddd on the navigation setup menu. This is not
   necessary for transfers it is purely for comparison purposes.

5: The creation date should follow the template
   DD/MM/YYYY HH:MM:SS
   DD=day
   MM=month
   YYYY=year
   HH=hour
   MM=minute
   SS=second
   
   Alternatively enter NOW and the current date and time
   will be used when the file is converted to a Garmin file.
   
6: The comment field should be a max of 16 characters
   (Garmin's protocol seems to suggest a 40 character field
   but the GPS45 only seems to handle 16, Other units with larger
   screens may handle more). If you enter more than 16 characters the GPS
   will ignore the extra characters.
7: Do not leave any field blank as this can corrupt the data fields when stored.

As these items are being edited using the built in data program no error
checking is carried out at entry time. I have included some error trapping
in the main program but I'm sure I haven't caught all possible errors. If the
GPS doesn't accept a particular waypoint it will give an error message and not
load it, the rest of the file will be loaded as normal.   


If you want to enter waypoints manually it is much faster and less error
prone to use the Psiway module.


When you have finished altering the data close the file.
You can now use the DATABASE WAYPOINT> GARMIN option in the FILE CONVERSION 
menu to convert the database file back to a Garmin file 
in preparation for sending it back to the GPS. 
I would suggest using a new filename here in case you have messed up!

When you send data back to the GPS it seems to just ignore incorrect data or
give a waypoint error message.

If you want to send almanac info, routes or track logs back to the GPS you
will need to register the program.



Editing of routes is now available in the same manner as editing waypoints.

As this part of the program is new it has not undergone the degree of soak
testing that the other routines have.

First you save get both route and waypoint files from the Garmin. The waypoint
file is required as you need a file containing all available waypoints. This
is to allow you to add additional route waypoints to thos stored in the routes.

Second you convert a Garmin route file to a Database route file using the
GARMIN ROUTES > DATABASE option under the FILE CONVERSION Menu.
This gives you a file which can be edited using the Data program.

A record in this file must stick to the following format


Route number    X% (0-19)
Route Name      XXXXXXXXXXXXXXXX (max 16 characters)
Route Waypoints XXXXXX,XXXXXX,XXXXXX,XXXXXX,XXXXXX (Max 5 names of 6 chrs)
Route Waypoints XXXXXX,XXXXXX,XXXXXX,XXXXXX,XXXXXX (Max 5 names of 6 chrs)
Route Waypoints XXXXXX,XXXXXX,XXXXXX,XXXXXX,XXXXXX (Max 5 names of 6 chrs)
Route Waypoints XXXXXX,XXXXXX,XXXXXX,XXXXXX,XXXXXX (Max 5 names of 6 chrs)
Route Waypoints XXXXXX,XXXXXX,XXXXXX,XXXXXX,XXXXXX (Max 5 names of 6 chrs)
Route Waypoints XXXXXX,XXXXXX,XXXXXX,XXXXXX,XXXXXX (Max 5 names of 6 chrs)

You can have 20 routes of up to 30 waypoints each.

Note the route name will be shown as ________________ if the GPS has
derived its name from your waypoints, rather than a manually entered
route name.

The waypoint names must be identical to the waypoint names stored in the
Garmin Waypoint file. If you want to use waypoints from a selection of
different waypoint files, copy all the files to the Garmin first and then
save the combined file back to the Psion. Use this combined file when asked
for the waypoint file.

The order of the routes within the Database file is not important.

When you have finished editing the routes save the file and exit the data
program.

Use the DATABASE ROUTES > GARMIN option under the FILE CONVERSION menu to 
compile an appropriate file to send back to the Garmin.
You will need to specify the database file, A waypoint file containing all
the Waypoints used in all the routes and a file to save the output to.
 
This option is quite slow if you are dealing with a large number of
waypoints and routes. 


Editing Track Logs is almost identical to editing Waypoints. There are a
couple of things to note.
Firstly the track point must be a 4 digit number ie point 1 is 0001 not 1.
Secondly when converting back to Garmin Track Log Files, the process can be
very slow as the database must be sorted to get the track points 
into ascending order first. The sorting routine is now much faster than in
previous versions, (thanks to someone who anonymously sent me a better sort
routine!). 
You can also now use an external sort routine if you prefer, the program now
checks if the file is in order before attempting to sort it. If the file is
already sorted the sort routine does not run.

There appears to be a problem in how Garmin GPS's handle dates in track logs,
when sending a track log back to the GPS all date and time information is set
back to the GPS default. This means that if you send the track back to the
psion again all the dates appear as 31/12/1989 00:00:00. This is not a bug in
this software, all software that sends tracks to the GPS has the same problem.
The field marked start point dictates how a track log is split up. If this
field is set to 1 the point will be taken as the start of a new track and
will not be joined on the GPS screen to the previous point. You can actually
use this to fix the breaks that occur in a track log due to "poor GPS coverage"
problems causing an artificial break. Just turn the break point back to 0 and
the track will join up across the gap.

The Split Track Database function gives you a convenient way of picking out
a section of a track log to keep on its own. E.g. say you had two different
journeys stored in one track log file. You can look at the database file and
note where each journey starts and ends, and then use the split function to
save them as separate files.


Under the special menu there is now an option to allow you to set the time on
the Psion to match the Garmin's time. This has been updated to allow you to 
give a local time offset from Greenwich mean Time.


Troubleshooting

The  most likely cause of trouble is the GPS not being set for the correct mode
of operation or the lead being incorrectly wired. The program will hang up
if it cannot maintain communication with the GPS receiver. There is nothing I
can do about this, it is a function of how the Psion handles its serial
interface - it only returns control to the program when the requested number of
bytes have been transferred, if not enough bytes are transferred it never
returns control. Under these situations the only way to exit the program is to
return to the system menu and kill the program using <Psion> <shift> <K>.


I have noticed that when you have finished uploading to the GPS it is usually
necessary to switch it off and back on again to get the nearest waypoints
displayed in the moving map screen. It is probably a good idea to always switch
the GPS off and on again anyway after uploading data to it.


There is a potential problem when converting database routes back to Garmin
routes. The system memory usage of this function is right on the limit on my
Psion. If anyone gets "No system memory" errors when using this function
please let me know. I could fix this but it would render the function
unavailable to people using GPS 90's for example which need more memory to
store waypoints.



PSIWAY
------


This option appears under the special menu if the Psiway.rsc file is present.

Psiway lets you create waypoints in several new ways.

Average GPS Waypoint.

This allows yo to create a waypoint based on the average of several different
readings taken over a period of time, to hopefully even out any errors.
You specify how many readings to take and at what time intervals. When
completed you specify what to call the waypoint, give it a description and it
is then sent automatically to the GPS. The description defaults to the 
Psion's current time and date.


Auto GPS Waypoint.

In this mode the Psion acts as an external keyboard for the GPS. When you
select this option the Psion gets a position fix from the GPS and lets you
enter a name and description. The waypoint is then sent to the GPS.

Manual ddd.ddddd Waypoint.

As auto GPS Waypoint except the latitude and longitude are specified by you
rather than read from the GPS. When completed the waypoint is sent directly to
the GPS.

Manual dddmm.mmm' Waypoint.

This is as the Manual ddd.ddddd waypoint except the latitude and longitude
are entered in degrees and minutes (on two separate lines). This is often
easier when entering waypoints from a map.
Note negative values represent south and west as normal. The negative sign
is only entered for the degrees not the minutes.

Manual OSGB Waypoint.

This allows you to enter a waypoint using OSGB Grid references or
eastings/northings. 




Wayedit.

These options allow you to directly edit a .way file either using
ddd.ddddd or dddmm.mmm' for latitude and longitude entry.
I have limited the accuracy to 5 decimal places to match the values
displayed on the GPS, this is equivalent to about 1 metre anyway. I
would love to see a map that could be read to this degree of accuracy!

You can now also edit waypoint files in OSGB coordinates, but it is very
slow to change waypoints, the on the fly conversions are a bit sore on
the Psion's brain! Only use this mode if you want to enter waypoints from
a map. If you simply want to rename waypoints use one of the other options
instead.

You can edit an existing ".way" file or start from scratch.

These options use the same text entry modes as for the manual waypoints.
The difference is that these options store the waypoints in a file rather
than sending them directly to the GPS. This lets you work in isolation from
the GPS entering several waypoints from a map for instance and then send
the complete file to the GPS at one go.

To move around within the waypoint file you use the "Action" option at the
top of the dialog box.
You can choose Add, Update, Erase, Search, Previous, Next, First Goto and 
OSGB Grid View.

Add.
You edit the currently displayed waypoint and it is then added to the
waypoint file as a new waypoint, leaving the original one unchanged.
The creation time will automatically be set to the current psion date
and time. If you want to set the description to the current date and
time simply enter a description of "NOW", without the quotes.
I know it's not as pretty as using a clean screen but it works! It also
helps for several close waypoints as you will probably only have to
alter the minutes and not the degrees

Update.
This will replace the current waypoint with your edited version. As usual
it will be stored as the last record in the file. The creation time will
be left unchanged unless you enter "NOW" as the waypoint description, this
will also change the creation time.

Erase.
Delete the currently displayed waypoint.

Search.
Search for a Waypoint name.

Previous.
Step back one waypoint.

Next.
Step forward one waypoint.

First.
Go directly to the first waypoint.

Goto.
Specify a waypoint to goto by number.

OSGB Grid View.
View current waypoint in OSGB Grid references.



Registration.

Send a cheque for 10.00 to
Jonathan Duff
7 Glenview Avenue
Holywood
County Down
Northern Ireland
BT18 0PX

If you don't have a UK cheque account you can send either a Eurocheque
for 10.00 or cash.


Or use Compuserve's software registration scheme
GO SWREG, Registration ID 10634
This will cost $20.


Phone 01232 425242
email 100767.1421@compuserve.com
web site http://ourworld.compuserve.com/homepages/Jon_Duff/homepage.htm

The most recent version of this program will normally be available on
my web page and also from the Compuserve "Palmtop A" forum.





Version Info.

Psigar 2.5,Psiway 2.5 25:09:1996
Fixed bug in OSGB file editing, which caused valid OSGB waypoints to be declared outside the applicable range.
Removed 50 metre offsets from six figure OSGB waypoint entry routines.
Changed the "Return to Psigar" menu item in Psiway for "Psion x" to "Psion r".

Psigar 2.4, Psiway 1.3 09:09:1996
Added OSGB file editing, removed some Nag screens and Operation aborted
dialog boxes.

Psigar 2.3, Psiway 1.2 18:08:1996
Added Limited OSGB support to Psiway

Psigar 2.2, Psiway 1.1 15:08:1996
Psiway.rsc, trkhead.tbf, rtehead.rbf and wayhead.wbf can now be stored
on any drive.
Fixed bug in Psiway which did not allow for 0 degrees, some minutes west 
when editing waypoints in ddd.mm.mmm format.
Fixed bug in countdown loop id Psiway average waypoint option
Extended max time in Psiway average waypoint to 999 secs and built in
escape option.

2.1
Fixed bug in Database > Garmin routes which allowed comments to be used
rather than waypoint names.
Fixed problem with invalid date in Garmin waypoint in recent GPS units.

2.0  16:07:1996
Added WayEdit to Psiway module. 

2.0alpha 14:07:1996

Added Psiway module.
Added Split Track Database function.

1.7 05:07:1996

Added improved sort routine to track log editing.


1.6 10:04:1996

Added track log editing.
Fixed a bug in the time setting function which gave you a 1 in 256
chance of the ime being set incorrectly.
Changed the registration details to a more secure method.
Fixed a problem with duplication of track log points when sending
from Psion to Garmin in some circumstances.


1.5 06:04:1996

Basically a modification to version 1.4 to allow for the larger length
waypoint and route records created by the GPS90. There is a potential
problem when modifying routes for a GPS90 as this seems to store a lot of
unknown information in the comments section of route waypoints and for
some route waypoints comes up with crazy times i.e. year 2007.

1.4 31:03:1996

Added new option to allow you to edit routes.
Added offset from Greenwich mean time to time setting option.


1.3 27:03:1996

Added new option to allow you to set the time on the Psion from the gps.
This version was a response to a specific request and not a generally
released version.


1.2 19:03:1996

Fixes bug in transfer of waypoints between Garmin Psion Data files.


1.1 15:03:1996

Initial release.




DISCLAIMER


The program is used entirely at the users own risk. I accept no
liability whatsoever for the use of this program. The protocols it is based
on are unpublished and are possibly incomplete or even incorrectly 
implemented. Any loss or corruption of data is at the users own risk.

Now with the introduction with OSGB Grid references I must also add that I
can accept no responsibility for any errors in the conversion routines, any
navigation carried out using PsiGar is entirely at the users own risk.


Copyright


The code used in this program is copyrighted by myself, please do not
attempt to reverse translate or modify the code in any way. 


Acknowledgements.

Special thanks to Bill Pechey and Mike Rudin for their help in converting OSGB 
grid references to latitude/longitude and vice versa.
