Read Me

===================================================

  AVR Butterfly GPS logger
  Code to avr-gcc/avr-libc
  
  by Oleg Volkov, Moscow district, Russia
  olegv@parallels.com

===================================================


Disclaimer:
-----------
- I'm not working for ATMEL.
- The code was derived from excellent gcc port of the original ATMEL AVR Butterfly Application
  by Martin Thomas, see his original comments in readme.gcc_port.txt
- The data logging part of the code were inspired by AVR Butterly Data Logger
  (see http://www.brokentoaster.com/butterflylogger/) though the code was written from scratch
  to ensure high degree of portability and extensibility. Now adding new data entries to the log is
  as simple as adding new entry to the log descriptor tables in the C source and in the python script for
  log download (btget.py)


Getting sources:
----------------
You can
- access SVN repository directly
    svn co https://butterflygps.svn.sourceforge.net/svnroot/butterflygps butterflygps
- download latest tarball from http://butterflygps.svn.sourceforge.net/viewvc/butterflygps.tar.gz?view=tar
- download latest release from http://sourceforge.net/projects/butterflygps/files/


How to build:
-------------
You need avr-gcc compiler in order to build the project. The WinAVR (http://winavr.sourceforge.net/) is
perfectly suitable on windows. To build just type make in the project directory. If you don't like
building just use butterflygps.hex file located in the project directory.


How to install:
---------------
To install the program onto the AVR Butterfly board you can either use the built in boot loader or ISP programmer.
The first approach may not work out of the box depending on the CPU fuses configuration. I used ARVISP mkII 
as a more flexible solution.


Connecting to GPS receiver and powering:
----------------------------------------
Any NMEA compatible GPS receiver may be connected directly to the AVR Butterfly serial port. I used GlobalSat BR-355
receiver. Note that GPS receiver typically requires 5V power. While the Butterfly CPU may be powered from 5V the on board
data flash does not. Powering from 5V source does not damage the flash but data reading/writing without errors becomes
impossible. So it's necessary to convert voltage down to 3.3V. I used single chip regulator LM2937-3.3 from
National Semiconductor.


Running:
--------
Enter GPS sub menu and the device will start receiving GPS data stream. You can monitor various data stream items, start/stop
collecting min/max values of the speed, altitude and the number of satellites available as well as start/stop GPS data log. 
The log is capable of storing 1 data frame per second during about 11 hours. The data buffer is being written to the log every 22 seconds.
Unexpected powering the device off doesn't destroy log data except the last unsaved data buffer. The log may contain more than one track so
you can start/stop log multiple times and all corresponding tracks will be stored separately. In case the log running time exceeds the
storage capacity the oldest data will be overwritten by the newest one so the log will keep the data collected during the last 
11 hours of running. You may reset the log any time to logically clear current log content or erase the log physically. Unless the
LOG_DEBUG macro is undefined you also have the possibility to run log test sequence which is useful for checking the storage for data
errors. The log format has checksums embedded in the data stream so errors will likely to be detected.


Log manipulation tools:
-----------------------
There are 3 tools written on python:
- btget.py
  Download the log and split it onto the individual tracks. Start the script first than choose GPS/LOG/TRANSFER on the Butterfly board.
  The script will do everything and quit. The log is being transferred at 9600 baud via the same serial port as used to connect to GPS
  receiver.
   
- btplot.py
  Track viewer. It also prints track statistics to the console. You can place cursor on the track by mouse clicking, move it by arrow keys
  and monitor track data at the cursor position on the console.

- btkml.py
  Export one or more tracks to KML format that can be viewed in Google Earth as long as other available geo-information such as maps,
  satellites photo ets.
  
All tools except btget.py may work either in 2D or 3D mode. Pass -2 or -3 command line option to the script to choose mode. To run tools
you need python and the following modules:
- pySerial   http://pyserial.sourceforge.net/
- numPy      http://numpy.scipy.org/
- matplotlib http://matplotlib.sourceforge.net/