TrekBuddy

[kruch]

User Guide

Requirements

* MIDP 2.0, CLDC 1.1
* without JSR-75/FileConnection API, you are limited to embedded map (however, you can customize it)
* without JSR-82/Bluetooth API, you will not be able to use external BT GPS

Location providers

* bluetooth - external bluetooth GPS
* internal - available on phones with JSR-179 support
* simulator - reads NMEA log and plays the track
* serial - serial port GPS (since 0.9.56)
* motorola - specific to some Motorola devices
* HGE-100
* O2 Germany GSM network

If the selected provider is out of service, despite it should be running, you may have a look at its status using Options->Info, where the last error of a provider may be shown.

Main data directory (new in 0.9.55)

One of the most important configuration options (see bellow) is Data Dir. It should point to a folder on the memory card with the following subfolders:

maps
resources
sounds
tracks-nmea
tracks-gpx
ui-profiles
wpts

You have to create this folder structure by hand!

Customization (new in 0.9.56)

UI
You may not like the default or may need different - larger, nicer, ... - icons for crosshair (crosshairs.png), course arrow (arrows.png), POI icons (pois.png) and/or waypoint symbol (wpt.png). You can create your own, preserving proportions, and copy your PNGs to the above mentioned resources folder.

Sounds
To change the sound that is played when a waypoint is reached, copy your custom sound (AMR encoding) to sounds folder as wpt.amr.

Datums
See Customization in wiki.

Keys

Use cursor key (or keys 2-4-6-8) to browse map; when held for a longer time, map scrolling should be faster. Track (or 5) will set the position to have current location in the center of the screen (if a location provider is running). Use 0 for changing crosshair background. Options ->Start/Stop starts/stops the provider (Simulator, Bluetooth GPS, Internal, ...). With 7 layers in atlas may be changed, 9 is used to change map in atlas.
Key 3 is for backlight control.
Key 0 is for changing day/night mode (HPS/CMS) or crosshair background (Map screen).
Key # to switch between screens (MAP, HPS, CMS).

If your device has touchscreen (handling improved in 0.9.56/further improved in 0.9.83), use it as more or less like a "big keyboard":


Map scrolling key mapping for Blackberry users:


Map screen

A small circlet in the right-top corner indicates provider status: red - out of service, blue - connection is being established, orange - temporarily unavailable (for external GPS this means that the last known valid position is older than 15 sec), green - ok. With tracklog enabled, the circlet is preceded with R.

The first OSD line shows latitude/longitude, the second (when extended OSD is inabled) current time, altitude, speed, course and a number of satellites.

Better position detection and navigation to close targets (aka HPS)

Press '#' to switch to HPS. You need to start tracking first to see position and/or navigation data. Move joystick left-right to change scale, up-down to change between averaged (green points) and non-averaged (lightblue points) calculated position.

"Computer-like" screen (aka CMS)

Press '#' twice to switch to CMS. See Themes.

Track recording

It is possible to record a track in either NMEA or GPX format. Be careful, NMEA log is a raw dump of what's read from GPS, so the log grows large quite fast. For internal provider, GPX format is always used.

With tracklog enabled, after the provider is started (Options->Start), a log file is created either in tracks-nmea or tracks-gpx, named either <current time>.nmea or <current time>-track.gpx.

Navigation

Press 1 to access navigation menu.

Supproted sources of waypoints are:

- file; either .gpx or .loc
- manually entered (WGS-84 lat/lon, either in dd mm.mm or dd mm ss.ss format)
- SMS
- application jar file; /resources/waypoints.gpx is tried first, then /resources/waypoint.loc

In any case, every waypoints source is available as "waypoint store". You can list the stores and their waypoints, view details and use for "navigation". Every file ending with .gpx or .loc found in wpts folder is avaliable as a "store" (action Waypoints in main navigation menu).

To start "navigation", select NavigateTo/RouteAlong/RouteBack while viewing waypoint details. In map screen in OSD, you will then be able to see distance and azimuth to the wpt. Similarly in HPS and CMS.

If you are in tracking mode, pressing Track (or 5), will switch between "navigation" info and "tracking" info shown in OSD.

The application can also record waypoints. They are stored in a separate file. In the waypoint management screen, select Record Current. You may name the waypoint, attach a comment to it, and if your phone supports media capture, also a picture. The recorded waypoints are stored in GPX file wgps-<start time>.gpx in the tracks-gpx folder.

For saving waypoints unrelated to GPS location, use Enter Custom. You may name the waypoint, attach a comment to it. Custom waypoints are stored in GPX file wmap-<start time>.gpx in the tracks-gpx folder.

When multiple waypoints are shown, you can change which labels are shown. Press shortly *, and then using 0, you can change to view current wpt name - current wpt description - all wpts names - all wpts description.

Location Sharing

Location - either actual or pointer position - may be send to another TrekBuddy. SMS reception has to be enabled in configuration (restart required for it to take effect). Location recevied via SMS is automatically enlisted in waypoints list, so you may select it to let the app navigate you to it.

Configuration (Options->Settings)

* Basic *

Startup Map - map or atlas to be loaded upon start. It is full URL. Example: file:///E:/trekbuddy/maps/map.tar (file on memory card in Nokia). It is not necessary to set the URL by hand - if loading via Options -> Load Map / Load Atlas succeeds, you are asked whether you want it to use as a default. For default map, leave the field empty.
Default Datum - default map datum (used when not detected)
Coordinates - selects display coordinates format
Units - unit system
Data Dir - root data directory for maps, tracks, waypoint and tracklogs

* Desktop *

Desktop - fullscreen - fullscreen display (restart required)
Desktop - no sounds - turns off provider status change acoustics
Desktop - nautical view - distance is shown in knots
Desktop - HPS wpt true north - azimuth to a waypoint is north-oriented
Desktop - OSD basic - display first (ie. coordinates) line in OSD
Desktop - OSD extended - display 2nd OSD line (time, speed, altitude)
Desktop - OSD no background - no grey background
Desktop - OSD larger font - larger font
Desktop - OSD bold font - bold font
Desktop - OSD black color - black color for OSD

* Location *

Provider - provider type selection
Tracklog - never/ask/always - trackloging
Tracklog Format - tracklog format selection
Capture Locator - locator for taking pictures linked to a recorded waypoint, usually capture://video
Capture Format - specify non-default picture quality like size, eg. encoding=jpeg&width=640&height=480 (see Options->Info->Snapshot encoding for supported encodings)
Provider-specific options:

Simulator delay - controls the speed of NMEA track replay
Location Timings - Internal provider parameters; default values are: 2,2,-1 for Motorola A780, 9999,1,2000 for Motorola E1000, and 1,-1,-1 for other devices


* Navigation *

Wpt Proximity - used in route navigation: when distance from active wpt drops bellow this value (in metres),a notification sound (wpt.amr) is played, and next wpt in route is selected as active
Route Line - dotted - route line is drawn dotted, not solid
Route Line - red - red line instead of black
Route Line - POI icons - drawn POI icons
Location Sharing - receive - enables location SMS reception (restart required)

* Misc *

Tweaks - optimistic I/O - may improve file loading performance
Tweaks - S60 renderer - may improve rendering performance and/or help to workaround memory leaks in some devices
Tweaks - forced GC - may help to workaround memory leaks in some devices
Tweaks - 1-tile scrolling - turns on alternative scrolling method that may help to avoid out-of-memory errors on some dvices

Maps

Custom maps

Howto and examples here.

Embedded map

Users with phones without JSR-75/FileConnection may replace the default map file in the jar with their own. Just prepare your map as described in the HOWTO Maps and Atlases, and copy it into the jar into "resources" directory.

The calibration file has to be "world.map" (.gmi format also supported, ie. "world.gmi"), slices list is in "world.set" file, and slices are in "set" subdirectory. Have a look at the default "world.map", "world.set" a "set" directory in the jar if unsure.

--END

* You are encouraged to read Ranger's User Guide too *

[simonzhan]

a good article!!!thanks!!!

[yky]

Hi,

I note that the described pairing of the phones and GPS receiver in the forum is always via BT.
Just got myself a HGE100 GPS enabler to use on my SE W710i. As this is not a BT but a cable connection, will the software still be able to detect the GPS data transmitted to the phone via the cable? If not, is there any way to make it work? Thanks

[Ranger]

Hi,
First of all, new docs are available:
http://wiki.trekbuddy.net
Yes, you can use HGE-100 with TB.
Depending on phone model, just try to use Internal location provider or you can use serial configuration. Described in wiki Configuration section.
Regards,
Ranger

[kruch]

http://wiki.trekbuddy.net/index.php/Configuration#Sony_Ericsson_HGE-100

[jumpjack]

I can't find any clue about how to zoom into a position!
And also how to load a map is not so clear...
And what's the difference among MAP and ATLAS?

I created an atlas using one of the tools in this forum, I copied the folder to the phone... but now how do I load it? Which file should I select?
Isn't there a complete "quickstart" tutorial, just to know how to load a minimal map and show my position on it?

[guest]

an atlas folder can look like this:
folder/
folder/atlas-name.tar
folder/15map/...
folder/15hyb/...
folder/13map/...
folder/13hyb/...

this example contains an atlas with zoom level 13 and 15, normal map and hybrid maps.

you have to load "atlas-name.tar" using menu -> load atlas.
you now can switch between zoomlevel using key "7" and switch between hyb and normal map using key "9".

map is just one layer, means one zoom level, atlas is the complete one, different zoom and/or differnet map types per zoomlevel.

havnt found a real guide, most things are here in the forum, its about try and error, or the like :)

Edit: there are some "sticky" posting, try to get some additional infor from them. cant say exactly, whats best to start with. but having an atlas already done, is a good start :)