RetroChallenge 2018/09 Final update – RetroGPS

This round of the Retrochallenge has been a blast, I accomplished all but two (or one and half ) of my goals. So let’s start with those items.

Realtime on GPS tracking to Apple ][ emulator, on a sailboat didn’t happen, no wind this weekend and some family items didn’t allow for some sailboat time.  That said real time tracking did happen in the car and I did construct a mount for the and laptop on custom hatch boards for the sailing vessel “Apple Pie”


and the second item was running the software on the Apple IIGS but the Kyan Pascal serial card drivers only work with Apple IIe serial card.

Those items aside I pulled out my original eTrex  GPS that has some screen issues, thus why I purchased a second one, but I was able to download the Waypoints and Tracks from the first one as a final test.

I did uncover a couple of issues that required some minor coding changes.

  1. The old GPS had some waypoints that had waypoint symbols that I had not coded on the first pass.  I added in symbols for “Information”, which is typically used for State information centers that are close to state boarders in the US.  “Rest Room”, Convivence Store and Tunnel, where a few others that were used in the older GPS




2. Downloading and displaying tracks.  The older GPS had the maximum of 10 stored tracks.  I had originally set up the array to store the coordinates of the tracks to hold 200 points, well there were some tracks that had in excess of 800 points, I upped the size to 1000, compiled and hoped it wouldn’t exceed the heap size, and in further testing it was fine.  Below are two plotted tracks, with the largest being a driving trip I had made from Pittsburgh PA, to Chicago Il, over 400 miles, and the video of this plotting at 1Mhz is attached to the Twitter post for this update, took over a minute to plot ;).



Here’s a second track of some kayaking at a local lake when I lived in North Carolina:


So in conclusion, I again found Kyan Pascal and the KIX shell to be a great development environment, and it would also have been quite good back in the day.  I did all my development in the environment and the only modern “cheat” was to up the system speed in the emulator, (though that would have been possible with accelerator boards as well on the original equipment) .

I kept the UI simple and clean using pseudo buttons and toggled through them with arrow keys, and most responses where single key entry.  Of course there are lots of enhancements that could be made including, saving multiple waypoint and tracks files, using more enhanced graphics drivers to include text, such as titles, waypoints on the plots, and looked into sending updates back to the GPS.

All in all with the timeframe of the Retrochallenge I’m pretty satisfied with what was completed and who would have know that GPS data could be transferred to an Apple IIe.



Update 5 : Download and Plot GPS Tracks

Downloading and storing previously saved tracks, follow the same protocol as described for waypoints, with differently defined packets for the data.  Tracks are stored with a header record and then a set of Track points stored with Latitude and Longitude data in each packet.


The programs downloads the track data into a file then the File Tracks can read and plot tracks from the data. This was fairly easy to implement from all of the previously written subroutines for communicating with the GPS, reading and writing to files.  The new bit of code was to convert decimal latitude and longitude to integer values normalized to fit on the 190 x 280 pixel graphics screen.   Shown below is a track download in progress.  The description from the track header is show and a counter of each track data point as it is transferred from the GPS to the data file is displayed.



Here you can see the GPS track on the GPS and the subsequent plot in the GPS software on the Apple II emulator, for two different tracks.

This first track is from a bike ride I took at a county park near my house, where I took two laps around the lake and as slightly different path on lap two.



And this track is from a day of kayaking at Moraine State Park in Western Pennsylvania.



Update 4 : Real Time Position Data in Text Out Interface mode

The Garmin eTrex has two primary ways to provide real time position information. In the Garmin interface mode that has been used to this point for turning the GPS off, down loading GPS info and waypoints, provides a protocol and packet definition for position, velocity and time (PVT) data.  As in the other functions this is a request/response protocol.  The challenge with this approach lies in the radian position type used to prove latitude and longitude positions in native 64 bit floating point format.  So instead of worrying about that conversion I used a different interface mode, a text out mode.  In the text out mode the GPS sends a character string out every second that provides data about position, date/time, velocity and altitude.  It’s a fairly straight forward layout as shown below.




My initial concern was, could an Apple ][ at 1 MHz keep up with the reading, reformatting and display of this information to catch a string every second and so far so good.

A couple of points about the data that is provided. The time is given in UTC – which is a standard universal non-time zone time, which this time of year is offset by 4 hours from my time zone.  So the string needs to be read in, converted to an integer and then subtract 4 hours.

The latitude and longitude are already in a decimal format and a hemisphere letter is also provided.

The only tricky (but not so tricky) part is calculate the velocity from a N/S velocity and an E/W velocity using the Pythagorean theorem sqrt(ew velocity^2) + (ns velocity^2)) and convert from meters per second to miles per hour (multiply by 2.23694 )

I prototyped the code, and a quick and dirty display and tested on my drive home from work with GPS hung from review mirror and laptop on the seat next to me, (see video in twitter : traidna )


The I reformatted the display to be a bit more visually appealing as shown below.




Update 3 – Retro GPS Waypoint Transfer

Here in update 3 the downloading for waypoints from the GPS to the Apple ][ and saving to a file for use has been completed. A waypoint is simply a unique address for any point in the world, but instead of the traditional street/city/state/zip format we’re used to for road travel, a GPS utilize waypoints expressed in mapping formats such as latitude/longitude.

In the Garmin transfer protocol the packet sequence starts with the sending of the PID_Command_Data to request the GPS initiates sending of waypoint data.

The Protocol this request is shown here:



The GPS responds by sending an acknowledgement packet (ACK) followed by the PID_Records packet (Packet 0) which includes the number of waypoint records that will be sent. Upon receipt of an ACK record from the program the waypoint records are sent one at a time such that when an ACK is sent from the program the next one is sent. Once all of the waypoints have been sent a final Pid_Xfer_Cmplt record is sent to indicate all waypoints have been sent. The program also counts the waypoints and displays to the number of waypoints sent in Packet 0, seen in the picture below. As each waypoint is received from the GPS the program displays the waypoint name and a counter for progress checking and each waypoints are stored in a file for reading and display.



The downloading and storing of the data turned out to be the easy part, utilizing subroutines for sending and receiving packets from the GPS INFO and GPS OFF in previous updates. The challenging part was in pulling the information out of the records, converting to a meaningful format for display.

The Garmin spec has a section on data types which gives the definition of standard data types such as chararters, variable length strings, character arrays, numeric types such as integers, long, float, doubles, and also more complex record types. The data is sent byte by byte during the transfer and it’s important to note all numeric types are sent in little-endian format, meaning the least significant byte is sent first. For example a 2 byte integer for the number 258 would be sent as two decimal byte 2 and 1 and would be decoded by 1*256 + 2 = 258.

The data types that apply to displaying the GPS name, latitude, longitude and gps type are :

Name          : variable length string (terminated with a 0)

Lat and Lon : Semicircle type (shown below)

Waypoint type : integer (then converted in the program to text per the definition in the spec also shown below)



The semicircle type provided an interesting challenge as the data passed for latitude and longitude each is an 4 bit long (integer) which includes a bit for hemisphere (North, South or East/West) and the rest is the number of semicircles, where 2^31 semicircles equals 180 degrees. Kayan Pascal does not have an included direct way to convert from integers and real Pascal data types. However there are integer to string, and string to real functions that were cobbled together to make a integer to real conversion routine, which was used to convert the 4 byte semicircle data to a latitude format such as N 45.12345 and longitude W143.12345 formats for display.



Retrochallenge 2018/09 – Post 2 – Reading GPS information

In my first post I described the HW and SW setup to establish communication between the Apple ][e emulator and the eTrex GPS.  Using that routines to communicate it is just a matter for sending other command packets to the GPS to exchange additional information.  The most basic request and return of data is the request for product information.  This uses packet ID 254, and the data is returned in a packet with ID of 255.

Here is the result of the request and formatting of the data by the Kyan Pascal program :


The eTrex GPS software version is returned along with Highway and Marine map versions.

The protocol works as such:

computer sends Packet with request for product (PID=254)
GPS sends ACK packet (acknowledgement of request) (PID=6)
GPS sends product data packet (PID=255)

In the picture below you will see the Garmin Serial Packet Format.  Always starts with a DLE character 16 decimal, followed by the packet ID, size of the data in the packet, followed by the data (number of bytes as sent in previous byte) .  Then there is a checksum, which is the two’s complement of the sum of the packet id, packet size and all data bytes.  finally another DLE (16) and an ETX (decimal 3) end the packet.




Without going into all the code I do want to note the I’ve written routines to send and receive packets.  To send a packet the array cmd[] is loaded with the command packet info and the returned packets are read into msg[].  A special routine to read and write ACK records was also written.  Here is a code snippet to show how the product request was set up, sent and read.


The next update will discuss the transfer of waypoints from the GPS to the computer and how to convert the 4 byte representation of latitude and longitude to floating point representation.

Retrochallenge 2018/9 Post 1 – Hardware Setup and Establishing Communication

Setting up the Hardware :

  1. Garmin eTrex Legend GPS with serial communication cable.  The connection is proprietary at the GPS and standard 9 pin serial at the other end.
  2. USB serial adapter to my laptop with mating 9 pin connector to the GPS cable.


Setting up development environment.

  1. The USB serial adapter is set up on COM3: in windows and the GPS serial settings are 9600 baud rate, 8 data bits, none – parity and 1 stop bits – Using the Garmin Serial Data format
  2. The COM3: port then is set to the same settings using the command at the command prompt : “mode com3: baud-=9600 parity=n stop=1
  3. In the winapple emulator settings, the Apple][ settings for port 2 are set to then windows com3: port

5. During my early research for this project I found a website and IRQ serial handler code that had been written for Apple II and Kyan Pascal.  Having familiarity with Kyan Pascal I decided to give it a go.  Here is a link to the site Apple ][ Super Serial Card by Dr. John B. Mathews.  I lifted the assembly routines written as in-line routines in Kyan Pascal and made one adjustment to the code to ensure the correct baud rate settings and set off to compile the routines.  I fully expected them to not compile, but they did.  I would be lying if I said I completely understand the code, but the point of this project is to communicate with the GPS so what I do understand is that there are routines to open the serial port, close the port and the read and write bytes to the port.   This is all that should be needed to communicate with the GPS.  You can read the website at the link above for additional technical details.  Below is the screen shot of the single change to the code I made :



In future posts I will go into the handshaking communication protocol for the GPS but to initially test that I have successful communication I set up a simple routine to initial message packets and send them via the serial port.  Shown below is the message that when sent to the GPS powers it down.  And what might be a first in my 30+ years of programming it worked on the first try.  After compiling and linking I ran the program, the TX led blinked on the USB-Serial adapter and the GPS powered off.   Now it’s off to see if I can establish bi-directional communication by requesting the GPS to send hardware/software information.









RetroChallenge 2018/09 – Project Entry

I have entered into my 5th RetroChallenge with my first Hardware/Software interface project.  Connecting a Garmin eTrex GPS via serial connection to both emulated Apple ][ and to Apple ][GS (in Apple ][ mode) real hardware.


The goals of the project are :

  1. write a program in Kyan Pascal on Apple ][ ( winApple emulator) and Apple ][GS original hardware to interface to a Garmin eTrex Legend GPS using serial connection.  This will require USB to serial cable on laptop using USB to serial converter, and serial cable / null modem to DB9 connection on the Apple ][GS.  The Garmin Device Interface Specification provides access to :
    1. Turn off GPS
    2. Request GPS software version
    3. Transfer Waypoints, Routes and Tracks
    4. Turn on / Turn off real time Position Velocity Time data (PVT
  2. Additionally use of existing Kyan Pascal / Assembly IRQ code for serial connection to the GPS
  3. Project will be documented at
  4. Twitter updates will also be used
  5. Stretch Goal will be to use the Winapple emulator version real time on my sailboat using GPS and Laptop thus the link to my picture 😉  with YouTube Video



In preparation I will be collecting and organizing the following hardware and software to prepare for this challenge:

  1. USB to Serial Adapter
  2. Apple ][GS serial to DB cable, Null Modem Adapter, M/M Gender Changer
  3. Garmin eTrex GPS, Garmin Device Interface Specification
  4. Pre-Written Kyan Pascal / 6502 Assembly Serial Communication routines
  5. Already have Apple ][GS, WinApple, Kyan Pascal Compiler, FloppyEmu SD card hard drive emulator.


Looking forward to RetroChallenge September 2019