;
;`-',
;.-.;""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""";, ,;
;`-';               AVEC V7b                    /\    |\           For Sony Playstation Portable    ;`-';
;.-.;           Vector Mapping                 //\/''/''/        with Homebrew Compatible Firmware  ;.-.;
;`-';           GPS Map Viewer                //''||' ||            First Demo Release 11/08/09     ;`-';
;.-.;                                        |/   |/  |/2009!           Last Update 30/09/09        ;.-.;
;`-';                                                                                               ;`-';
;"""'"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""'"""'


Hi Guys,
You read correctly, at last, a vector mapping GPS program for the PSP is available!
Although not the first vector mapper for the Sony PSP, it is the first GPS vector mapper, and the fastest.

This program reads and displays MP (polish format) map files which are very common among the Garmin
custom mapping scene, and can make use of a GPS device connected to the PSP serial port to display your
current location on the map. A seperate version of this program makes use of the PSP-290 USB GPS device.

A biult in converter (or seperate  Windows converter program) can be used to
convert to a custom indexed file format that greatly improves drawing speed at higher zoom levels.

The Program also has a "Find Place by Name" feature, and a "Track Up Display Mode" that work similarly to
the respecive modes of a commercial GPS unit. One objective for this program are to discover, and expand
on functionality that is not available in commercial GPS units.


       **************************************** Disclaimer ******************************************


The AVEC program is provided for free, as it is, without warranty of any kind, either express or
implied, including, but not limited to, the implied warranties of fitness for a purpose.
Without limiting the foregoing, the author of this program makes no warranty that:

   1. the software will meet your requirements
   2. the software will be uninterrupted, or free of errors.
   3. any errors found in the program will be corrected.
   4. documentation provided with the program will be accurate, complete, or up to date.

Use of this program is at your own discretion and risk and with agreement that you are responsible for any
damages or loss of data that results from such activities.


       ********************************* Grant Of Software License **********************************


The AVEC Program is free to use, but I retain ownership of my software, and grant of license to use
it is under identical terms of GPS Trackmaker license agreement (reproduced in part with permission),
that pertain to preservation of protected ecosystems. View the entire agreement for GPS Trackmaker:
http://www.gpstm.com/downloadscontract.php

"LICENSE GRANT

The author grants a non-exclusive license to use the program, free of charge, if the user:
Does not use the program for illegal purposes;
does not practice activities that destroy or degrades the environment;
does not practice polluting activities;
does not throw trash on the ground or through the car’s windows;
when going to the beach and creeks takes his trash back until finding a trash collector;
does not practice any activities that hurts animals, like hunting, out-of-season fishing, pigeon shooting,
dog fight, etc.;
does not buy wild animals that, by law, may not be created out of their natural environment;
has ecological conscience and protects nature.
People that for any reason do not fit the conditions above, are expressly forbidden to use the program."

License to use any version of the AVEC program also require adhesion to the following terms:

When the user visits a Beach or other body of water, National Park or other protected environment,
he or she leaves no damage to live vegetation, leaves no unnatural polluting material, or litter,
and removes non-combustible material from fireplaces, or litter that may have been left by other people
if it is reasonable to store and carry it with your own rubbish.


The following notice is provided as a condition of using "NMEAP", a C NMEA sentence parser for programmers
using serial GPS devices in their applications. the 1.50 kernel mode version of AVEC GPS uses this code.
NMEAP can be found here: http://dmh2000.com/nmea/nmeap.shtml

Copyright (c) 2005, Daveh. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that
the following conditions are met:
    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in the
      documentation and/or other materials provided with the distribution.
    * The name of its contributors may not be used to endorse or promote products
      derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY DAVEH "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL <copyright holder> BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


       *************************************** Installation ******************************************


To Install the 1.50 kernel mode version of the AVEC program (uses serial port to connect to GPS devices),
copy the program folder to the homebrew game folder of your PSP.
This could be the PSP/GAME150 folder for newer firmware, or PSP/GAME folder for original 1.50 firmware.

The program will also work with original 1.50 firmware as long as the program folder is kxploited.

To Install the 3.xx user mode version of the AVEC program (uses USB port to connect to the PSP-290 GPS),
copy the program folder to the homebrew game folder of your PSP. This should be the PSP/GAME folder,
or PSP/GAME3xx folder (xx representing the last digits of your firmware version).

Both versions of AVEC are tested with a 3.52 M33 firmware PSP unit. This is the last true 1.50 kernel
hybrid firmware. The program is known to work with other firmwares as well, but I have not tested any.


       **************** Serial GPS Device Connection (1.50 Kernel Mode Version) **********************


Just about any serial GPS device can be used with this program. The NMEA parser that handles GPS communication
has been tested with a Garmin 60CSx. Any serial GPS setup that works with the MapThis! PSP application should
also work with AVEC, since they use the same NMEA parser routines. The serial speed of the GPS device connected
to the PSP must be set to 4800 baud.

The Garmin 60CSx is connected to the PSP differently from normal to get it to work since it has real RS232 output.
I have detailed how to connect the PSP to a Garmin 60CSx, and the Garmin GPS18PC (GPS mouse) in this thread:
http://www.dcemu.co.uk/vbulletin/showthread.php?t=69316
The GPS18PC is not self powered, and a battery pack must be used to power it if it is to be connected to the PSP.


       ******************* PSP-290 GPS Device Connection (User Mode Version) *************************


The User Mode version of AVEC for newer firmware versions is tested with the official Sony PSP-290 GPS device.
It can also be used as a map viewer without the GPS device attached.

I have found that the PSP-290 GPS suffers from drift compared to the serial GPS device that was tested.
The course also seems to flutter about while standing still, and it is hard to aquire a position fix indoors.
The unit functioned very well in a moving vehicle.


       ****************************************** Usage **********************************************


The first time the program is started, you will see an intro screen which shows the functions of most buttons.
This screen is disabled for future sessions because it is only displayed when a config file does not exist,
and a default config file is created by the program on it's first session.

In addition, you can press the square button to display a magnifier window, and using the analogue joystick
while holding down the Cross button will let you drag the map unless track up display mode is enabled.

Maps should not be too large, since the program drawing will slow down as map files get larger.
One large city at a time should work at a good speed, or a topograph of a mountain, but it's best to experiment.
Testing was done with individual detail map tiles from the Garmin Mapsource Metroguide Australia CD.

When a map is loaded, the starting position is at the upper right most point of interest or line.
The map is initialy displayed at the highest preview zoom level where the entire map fits in the screen
area, and wire polygons are displayed.

Zooming in any closer than the initial zoom level will remove the wire polygons, and zooming in a little
further will reveal full map detail. Points of interest are only shown at high zoom levels.

If you use a map with any land contour lines, it is assumed by the program to be a topographic map,
and the background will be coloured a shade of green, otherwise the background is black.

The Triangle button activates the main menu where GPS mode can be toggled, and other configuration options
can be set and saved. GPS mode must always be switched on manually. This option is not saved.
A new map file can also be selected from the file browser on the left side of the menu screen, and loaded
by pressing right on the direction pad. The START button also activates this menu.

A GPS information bar will appear at the bottom of the screen which displays the last time, speed, and
location aquired from the GPS device.

The user mode version of the program also displays a GPS signal strength meter while GPS mode is active.
Red bars indicate no signal. Orange bars represent satellites in view. Green bars represent the number
of satellites used to aquire the current position fix.

The "Find a place on the map" option allows you to enter a place name and have the program locate the
position of that place on the map. The place can be a point of intrest or any line type such as a street or
creek for example. Enter the place name into the "Enter Name" field with the directional pad, or optionaly
use the analogue joystick to select letters and spaces only, and then press Circle to locate it on the map.
You do not have to enter the entire name. Just enter enough letters to narrow down the search.
If the place is a street, or other type of line, it will be coloured pink when it is displayed on the map to
help you locate it until you search for another place.

While in viewer mode you can use the analogue joystick to point at a street, and it's name will be displayed.
In GPS mode, the current street name at your location will be displayed if it is touching the crosshair.
The names of all streets in view are displayed at the highest zoom level.
The functionality of the program dealing with street names only works if names are available in the map file.
Many open source maps do not contain much street lablel information. Original Garmin Mapsource products are
best for this.

The track up display mode will allow you to rotate the map with the joystick while GPS mode is off,
and while GPS mode is on, track up display mode will auto rotate the map in the direction of travel aquired
from the GPS device.

The Home button exits the application.


       *************************************** 3D Terrain Mode ***************************************


The 3D terrain viewing mode allows you to view and rotate topographic maps in 3D. The map grid, and all
points of interest are disabled in 3D terrain mode, as well as all lines other than land contours.
Track up mode allows the user to rotate the map, just as it does in top down view mode.
There are two levels of terrain exaggeration that can be selected in the configutation menu screen.

The red pointer shows your current position at sea level when 3D terrain mode is active. When 3D terrain
mode is active in GPS mode, a green pointer shows your current position with the elevation received from
the GPS device, and positioned with a y axis adjustment to represent your position on the 3D terrain model.

The green pointer should be directly on top of the red pointer if the altitude is zero, or the GPS has not
aquired a three dimensional position fix yet. The green pointer may disappear off the top of the screen if
the elevation is higher than the top of the screen in the current frame.


       ******************************** Differences Between Versions *********************************


There are some minor differences between the two distribution versions of AVEC GPS.

Both are able to connect to a GPS device, however, the 1.50 kernel mode version can only connect to a
serial GPS device, and the user mode version can only connect to the Sony PSP-290 USB GPS device.

When connected to a compatible serial GPS device, The 1.50 kernel mode version updates the screen when
either of two valid NMEA sentences are recieved. This begins to happen before the GPS has a position fix,
and the map will be set to coordinates of zero degrees latitude and zero degrees longitude.
When the user mode version of the program is connected to a PSP-290 USB GPS device, the map screen is
only updated when information is recieved from the GPS while it has a position fix. If the PSP-290 is
functioning correctly, you will see the UTC time updated every second on the GPS information bar even
before the device has aquired a position fix.

The 1.50 kernal mode version disables sound while GPS mode is active, and the user mode version does not.

The user mode version of AVEC is the only version that has a signal strength / position fix indicator.
This was implemented because the PSP-290 has trouble aquiring a position fix indoors or under clouds.

The 1.50 kernel mode version of AVEC uses the power LED as a GPS mode indicator. The PSP's green power
LED will only be lit while GPS mode is active, but does not mean a position fix has been aquired.
The behaviour of the power LED is normal if the PSP is plugged in to the power cord. In this case it
is orange while the battery is charging, or green when the battery is charged.

The 1.50 kernel mode version is exit by holding down the Home button, while the user mode version uses
the exit callback. This is the familiar Yes/No exit screen seen in official games, and most homebrew.

The 1.50 kernel mode version may have slight differences in the data fields shown on the debug information
panel that is displayed when the Left Trigger button is pressed.


       ******************************************** Maps *********************************************


Free Garmin compatible maps are fortunately very common on the internet. It is also very fortunate that
most of them are easily converted to Polish format for use with this program.

You can use Garmin City Navigator or Metroguide maps if you own such a Map product.
Just open a Garmin IMG file with the free version of GPS Mapedit: http://www.geopainting.com/en/
save the map file in Polish format, and you're good to go. Garmin NT products are not supported
by Mapedit, and therefore, cannot be converted to Polish format by any known means.
Polish format maps produced from Garmin map files do not need to be unlocked for use with AVEC.

There is a limitation on map size which is roughly 16 Mb, and more detailed maps will take longer to draw.
You can easily cut a part out of a map with the trim tool in Mapedit. One city at a time is recommended.

Free OSM Australian Street Maps:
http://users.tpg.com.au/users/stevez/OSM/download.html

Free Australian Topographic and Street Maps:
http://www.gpsoz.com.au/tracks4australia/

Free Worldwide maps:
http://gpsmapsearch.com/

Free US Topo Maps:
http://www.gpsfiledepot.com/maps/state/all


       ******************************** MP Converter Tool for Windows *********************************


A Windows MP Converter tool has been included with AVEC V3 (and later versions) for the conversion of map files.
The program converts mp (Polish Format) map files into mpi (Indexed Polish Format) map files.

Although AVEC still supports mp files, the mpi format is designed specifically for use with AVEC to significantly
increase speed. It is recommended that you convert your Polish Format maps for use with AVEC.

AVEC is also capable of converting mp files to mpi files, but it is a lot slower than the Windows MP Converter.

Documenation for the MP Converter tool is in a seperate readme file in this program package.


       ************************************** Troubleshooting *****************************************


There are a few considerations to take into account when using AVEC. One is that the program uses most of the
memory of the PSP 1000 (fat) model. In fact, there is under 1 Mb to spare once the program is loaded,
so if AVEC crashes the PSP on startup, you might be required to disable any game plugins in order to load it.

Currently, the serialy connected GPS device must be configured to 4800 baud to be recognised by AVEC.
AVEC gains position information from the GPRMC and GPGGA sentences sent by the GPS device. These sentences
should be set to be sent by default for most GPS devices, but if this is not the case, the GPS device should
be reconfigured to send them.


       ****************************************** Credits *********************************************


Thanks to Deniska, MPH & Psyberjock for perfecting the routines that provide PSP-290 functionality.

Thanks to Deniska for getting Daveh's serial NMEA sentence parser code working on the PSP.

Thanks to Starcat of the Amiga scene for help with vector rotation code and optimisation.

Thanks to Greg, admin of PSP-hacks.com for providing the donation for my PSP-290 GPS device.

Thanks to pc-mobile.net for providing a sample PSB USB extension cable for remote mounting of the PSP-290.


       ******************************************* Media **********************************************


AVEC has it's own page on my personal website: http://www.freewebs.com/defxev/AVEC.htm

There are also a few YouTube videos uploaded to demonstrate some features as they were implemented.

AVEC GPS Special Time Lapse Photography Demo:
(Shot with the PSP-300 Go! Cam. Camera functionality will not be included in any public release)
http://www.youtube.com/watch?v=UrahMeju7bY

AVEC GPS V6 Street Labels Demo:
http://www.youtube.com/watch?v=L8s6MS6sTJ8

AVEC GPS V6 3D Terrain Demo:
http://www.youtube.com/watch?v=GzvRohPRR-8

AVEC GPS V4 Track Up Display and Rotation Demo:
http://www.youtube.com/watch?v=BsHa1qAEUk4

Find Place by Name feature with Joystick Angle Letter Selection and Auto Complete:
http://www.youtube.com/watch?v=gvK8lX_fy-I

AVEC Indexed Map File Demo:
http://www.youtube.com/watch?v=GW2t19Aqls4

AVEC Early Map Rendering Demo:
http://www.youtube.com/watch?v=ZvhbknIGrpM


       ***************************************** Donations ********************************************


*Donations*
License to use this program will remain free, but I am accepting donations toward new hardware and development.
You can encourage future program and/or hardware development by sending a donation. Contact me on the PSPU,
Austech, or these other listed forums. My user name is Art on all of them, or click the donation link on any of
my project web pages.

I have valuable use for low capacity Memory Sticks for use while programming. If you like this program,
please consider donating the 32Mb Memory Stick that came with your PSP once you have upgraded,
or perhaps the low capacity Memory Stick that comes with some Sony Ericsson mobile phones.
I also have use for any broken PSP hardware or Canon digital camera hardware.

Thanks goes out to Jason & Jared, a Father & Son team from QJnet forums for being the first to donate a pair
of Memory Sticks! It's much appreciated! :) Keep up the green electronics projects! Thanks also to MjW,
Moose Island, and lifey for their kind donations of PSP Memory Sticks.
Cheers, Art.

http://forums.ps2dev.org/viewforum.php?f=14
http://forums.qj.net/f-qjnet-sony-psp-forums-48.html/
http://www.dcemu.co.uk/vbulletin/index.php
http://www.psp-programming.com/forums/
http://www.psphacking101.com/forum/index.php?c=1
http://www.freewebs.com/defxev/


       **************************************** To Do List ********************************************


This is a list of features I've thought about implementing in the future. They may, or may not appear in
future versions of AVEC GPS.

Improve size limit on map files by reading directly from Memory Stick rather than loading to RAM first.

Add support for setting waypoints and creating Garmin compatible track logs, and display them on screen.

Add more configuration options such as 4x zoom option for magnifier window, auto load default map, and
configurable baud rate for serialy connected GPS devices.

Improve efficiency of search routines to improve speed.


       ************************************ Program History Log ***************************************


VERSION HISTORY:

AVEC V7b (30/09/09) :
- Bug fix for colour coded file list in the file browser.

AVEC V7 (30/09/09) :
- New implementation for associating groups of adjoining maps with each other, allows automatic transition
  from one map file to another as the user's position moves of the edge of individual map tiles.
- Changes to file browser prevent navigation out of the map folder, and filters files appearing on the list.
- Implemented a new circular file broswer style and operation with the configuration menu now built in.
- File browser list is now colour coded for easy identification of mp, mpi, and set file types.
- Right trigger now rotates the map by one degree in 3D terrain mode.

AVEC V6 (25/09/09) :
- Implemented 3D terrain view mode for topographic maps with two configurable terrain exaggeration levels.
- Fixed bug present only in user mode version where the grid was not rotating with map while in GPS mode.
- Removed canvas size option from the configuration menu.
- Changed position indicator slightly to improve visibility.
- Added street names to map display at highest zoom level if street names are available in the map file.
- Fixed zoom routine to ensure highest zoom level is always available.
- Changed the default GPS mode zoom level to the highest zoom level.
- Removed delays in image capture routine that were not supposed to be present in any public release.
- Improved the look and the control of scrolling in the configuration menu.
- Sound now works in GPS mode for user mode version only. USB GPS routines are running in a dedicated thread.
- Implemented new compressed mpi file format resulting in faster map file searching and smaller file size.
- The PSP-290 USB GPS unit can now be plugged in after the user mode version of the program has started.
- Fixed bug in mpi converter routine. Program would crash if a street name began with an open bracket character.
- Program no longer adjusts the PSP clock speed. By default, the PSP will run at 222MHz.

AVEC V5 (15/09/09) :
- Implementation of Deniska's PSP-290 test program routines provides compatibility with the PSP-290.
- Added signal strength indicator to user mode version of the program for PSP-290.

- Added colour cycling circle around pointer crosshair to make it easier to see.
- Improved joystick controlled map rotation feature for track up mode without a GPS device.
- Greatly improved the speed of rotation routine for faster drawing in track up display mode.
- Improved accuracy of screen position by removing zoom levels that cause float rounding error.
  This fixed a bug in the find place by name feature where the found place may not have been on the screen.
- Fixed bug in screen capture routine. Saved images were horizontaly offset by one pixel.
- Improved text entry method for find place by name feature by implementing optional analogue selector.
- Fix to projection routines to resolve a problem that caused some lines and polygons to appear squashed
  toward the bottom of the screen. This may have added a noticable processing overhead.

AVEC V4 (09/09/09) :
- Lines for roads increase in thickness at the two highest zoom levels for street maps.
- Some improvement to map edge detection routine to accomodate large base maps of entire continents.
- Fixed bug causing two images to be saved for every frame when save frames option is enabled.
- Zoom level is auto set to high when GPS mode is enabled, but can still be adjusted.
- GPS parser runs in seperate thread so gps mode is faster, and buttons are responsive in GPS mode.
- Changed altitude field to speed (kilometers per hour) in GPS information bar.
- Intro screen is only shown once on first use, then program starts in the file browser screen.
- Serial port can be restarted if plug is pulled out in GPS mode by turning GPS mode off and on again.
- Fixed option to show points of interest in GPS mode. This option was present in V3, but did not work.
- Fixed config loader to prevent program starting in GPS mode, even if saved in configuration menu.
  Starting in GPS mode caused a problem. This issue may be resolved later to allow starting in GPS mode.
- Implemented a track up display option in GPS mode so map appears to move in the direction of the vehicle.
- Implemented map rotation mode using the analogue joystick to rotate the map when GPS mode is off.
- Implemented image sequence player for playback of previously captured image sequences.
- Added show grid and canvas size options to configuration menu.
- Various other improvements.

AVEC V3 (01/09/09) :
- Fixed extra points of intrest bug introduced with V2.
- Map can now be dragged when the crosshair reaches any edge of the screen.
- Inclusion of new utility to convert maps to Indexed Polish file format.
- Faster map search using Indexed Polish file format making real time GPS navigation possible.
- Improved speed with original Polish file format, and retained backward compatibility.
- Improved detection of topographic map type so green land colour is applied faster.
- Increased map file size limit to approximately 16 Mb.
- Implemented a backbuffer so screen drawing is hidden and screen flicker is eliminated.
- Removed Neoflash competition splash screen.
- Added icons for eighteen point of interest types including summits, campsites, and parks.
- Fixed a bug that caused an incorrect label to be shown for unnamed lines.
- Introduced a configuration menu screen and configuration save option.
- Implemented a search for places by name feature with auto complete text entry.
- Map files shown in file browser are now sorted in alphabetic order.
- Various other improvements.

AVEC V2 (20/08/09) :
- Added border around magnifier window.
- Added progress bars to interface.
- Eliminated most of the overhead of searching points by searching points at the same time as lines.

AVEC V1 (18/08/09) :
- GPS support implemented through serial port.
- Implemented experimental wire polygon support.
- Implemented file browser for map file selection.
- Improved map file parser to work with maps of any location.
- Decimal degree labels now displayed on map grid.
- Implemented point and click map navigation method.
- Implemented feature to lookup names when the pointer is placed over a street or trail.
- Implemented a magnifier window that follows the cursor position around the screen.

AVEC Demo (11/08/09):
- Basic map viewer for demonstration.



       ************************************************************************************************


