THE COMPASS PROGRAMS

This webpage provides download links for the software, as well as a narrative description of the changes performed on the PIC source code, and the QuickBasic IBM display program. Only the external, “observable” changes in the display program will be discussed here, but the changes in the PIC code will be described in greater detail...

On 2 March 2001, I added a new version of the PIC program, ( called MAGDOPP ) which sums the compass heading directly with the DF bearing, and ( therefore ) reports all DF bearings ( through the RS232 link ) in magnetic degrees, instead of relative degrees. This allowed me to restore the original Agrello DF message format, so the messages can be employed with other types of display software, ( GPSS, etc. ) and also with APRS software.

EXPLANATION : The earlier version of "Doppler with compass" PIC code transmitted the DF bearing ( in relative degrees ) and the compass heading ( in magnetic degrees ) as SEPARATE ITEMS OF INFORMATION in each RS232 message... they were "summed together" in the display program provided on this page, but the resulting RS232 message was no longer APRS compliant.

No detailed explanation of the PIC code for MAGDOPP will be offered here... the digital readout on the DF ( if installed ) will still indicate RELATIVE degrees. If the compass fails ( or is not installed ) the MAGDOPP program asserts a compass heading of "000" degrees, so all reported DF bearings will ( therefore ) revert to RELATIVE degrees.

The reader is encouraged to read the page called NOTES, regarding some peculiar problems I observed when I ( finally ) used these programs on a portable computer... and the methods I used to deal with them.


THE DOWNLOADS

Here are the downloads.

The PIC files are ordinary text files, but the .asm and .hex filename extensions might confuse a word processor... If you want to change the extension, you can use NOTEPAD to open them ( select “all files” in the directory display window ) and then use SAVE AS to create a new file with a different extension. ( You must also enter the new file extension )

The display software is compiled code, and cannot be read as text.

PIC source code for [compass only] : 14 KB, .asm file extension
PIC source code for [compass with DF] : 40 KB, .asm file extension
PIC object code for [compass only] ( Intel hex format ) : 1 KB, .hex file extension
PIC object code for [compass with DF] (Intel hex format ) : 2 KB, .hex file extension

The following PIC Doppler code was added on 2 March 2001... It reports DF bearings directly in magnetic degrees, instead of relative degrees, in APRS - compatible "Agrello DF" message format :

PIC source code for [MAGDOPP] : 39 KB, .asm file extension
PIC object code for [MAGDOPP] : 3 KB, .hex file extension

[ IBM PC display program ], ( ver 3.1) with compass - driven azimuth scale. ( compiled, 88 KB, about 2 minutes download @14.4 K )

If you want the source code for the display program, send me an e-mail and ask for it...

It is written in QuickBasic 4.0.


PIC PROGRAM VERSIONS

Two different versions of the PIC code are provided... one allows the compass to be operated as an autonomous instrument... no DF functions are provided, and the compass information is “disguised” as an Agrelo format DF bearing message. This allows the resulting RS232 message to be directly displayed on the IBM software, as a DF signal... I created it to demonstrate ( to myself ) that I knew how to operate the compass, and extract meaningful information from it... If you desire, you can use it to build ( and test ) the compass before building any of the DF circuits... ( or use it as a separate compass, with a few mods )

The resulting code was ( eventually ) merged with the pre-existing DF PIC code, yielding a second version of the PIC DF program, suitable for field operation... one that transmits both DF bearing information and compass heading information, in each RS232 message. The resulting message is no longer compliant with the APRS Agrelo DF format, but it will drive the new version of IBM display software, provided on this webpage. ( it will also drive the old version, as well ) Eventually, I will try to identify a more “APRS compliant” way to generate and send compass and DF information... probably as separate, alternating RS232 messages. At present, the message has the following form :

%XXX/Y/ZZZ(cr)

Where :

XXX = DF bearing, degrees relative to vehicle heading.
Y = “7” ( signal quality, fixed at 7 in this software )
ZZZ = vehicle heading , degrees magnetic


PIC CODE CHANGES FROM ORIGINAL ( NON - COMPASS ) VERSION

This section describes changes that were performed on the original PIC program, to add the compass functions. No description will be offered for the “autonomous compass” version of the PIC program.... it is fairly simple, and half of it uses pre-existing PIC code for the serial RS232 routine... code that was explained in the original RS232 interface portion of the website.

The original PIC code would “squelch” the DF messages, if no DF data was available. The new version was modified to transmit messages at all times, even if no valid DF data was available... if no data is available for 100 successive antenna rotations, the PIC will transmit a message containing “999” in the DF data field. This allows the azimuth scale to be updated in the absence of a DF signal. If the compass fails ( or is not installed ) the compass data field contains “999”. Compass failure is detected by a “timeout” function, based on observations of the EOC ( end of conversion ) status line, provided by the compass... if the compass fails to complete its calculations after 10 successive RS232 message transmissions, it is deemed “failed”, and the compass message is change from the last valid compass heading to “999”. The software continues to “work” the compass, attempting to re-establish normal operation.

The program will not “hang up” if the compass fails, or if valid DF data is lost... The compass normally takes hundreds of milliseconds to generate a valid heading, so the PIC code “time shares” the compass tasks with the main DF tasks...

It begins by generating a stimulus to start the compass conversion process. A flag is then “set”, to indicate that the compass is “working” on a answer. The PIC chip continues to the rest of the program, and sends an RS232 message, using the last valid compass heading.

During the next program loop, the EOC line ( from the compass ) is observed to determine if the compass conversion is completed. If not, a “timeout” counter is incremented and checked to see if the compass has failed.

If the contents of the timeout counter exceeds the maximum allowed value, the last valid compass heading is changed to “999”. A flag is set to indicate that the compass should be “re-started” during the next program loop, and the program proceeds to generate the next RS232 message, using “999” for compass data.

If the contents of the timeout counter do NOT exceed the maximum allowed value, then it is assumed that the compass is still working on an answer, and no action is taken... the program proceeds to generate an RS232 message, using the last valid compass heading.

If the EOC status line indicated that compass calculations are completed, the program “clocks” the data out of the compass, converts its to ASCII, and stores it as the “last valid heading”. The timeout counter is zeroed, and a flag is set to indicate that the compass should be “re-started” during the next program loop. ( that is, begin another conversion )

If no DF signal is present, then the Doppler circuits will not generate a zero-crossing detect signal, and there will be no CALIB 1-shot “stimulus” to start the generation of a DF message... Under these conditions, the compass updates would also be lost, so the 360 RESET routine was modified to generate an RS232 message “automatically” if the number of 360 resets ( detected at pin 1 ) exceeded 100, without any CALIB pulses. The counter that stores this number is reset to zero each time a CALIB trigger is detected at pin 6.


DISPLAY PROGRAM CHANGES

The “fault” conditions are reported by the DF with “999” entries in either ( or both ) of the message data fields... Either of these “fault” conditions will cause the display program to “beep” when the message is recieved, indicating that some of the data is not valid.... the invalid data is not used, and is discarded by the display program. Otherwise, the compass heading is used to drive ( i.e. rotate ) the azimuth scale, and EVERYTHING which is displayed on / around it... that includes all the ( previously recorded ) DF vectors, the MAG and TRU heading bugs, and the cursor line. The vehicle heading readout ( located at the 12 o’clock point on the display ) will also be updated automatically. If acquisition is turned off, the heading information is still recieved and used to drive the display, but DF data is ignored.

The left/right ARROW keys on the numeric keypad were originally used to update the vehicle heading, and they still can be used to perform this task... they remain active, and can still prove to be useful, to correct any compass errors caused by misalignment between the compass axis and the centerline of the vehicle, or to manually correct any other compass errors, caused by magnetic anomalies, in “real time”. ( assuming you can somehow detect them, and measure them )

Aside from these changes, most of the changes to the display program are “cosmetic”... the various keystroke “legends” were abbreviated and / or moved, to remove them from the display area used by the azimuth scale. ( the “viewport” ) This was done to reduce the “screen flash” that occured whenever the azimuth scale was updated. It was quite annoying on a desktop computer, but I later found that the LCD display of laptops exhibited enough “persistance” to render the flash undetectable.

This program will probably be updated with enhancements and improvements, from time to time...

[HOME PAGE][NEXT PAGE]