# Blackstar
## Introduction

Blackstar is a free application that runs on most BlackBerry smartphones. It allows the user to use the built-in GPS (or an external Bluetooth GPS) to perform point-to-point navigation. It also has a series of Geocaching-specific enhancements that allow Premium Geocaching members to import Pocket Queries or extract data from bcaching.com.

## Installation and support

The software may be downloaded from the project page above, or can be installed from Blackberry App World.
Support is available at the project forums, which can also be found at the project page.

## Getting your first GPS Lock

When you start BlackStar, it will attempt to get your location using whatever GPS is set up on your device. While the lock is being acquired, you'll see a count on the screen. This is the number of seconds BlackStar has been trying to acquire a GPS lock (not a number of satellites acquired).
Once it accomplishes the lock, it will start showing your GPS coordinates and altitude, along with speed and a compass indicating the direction you are moving (this is not a magnetic compass - it compares your current location to your last few location to interpolate the direction you are moving, so if you slow down too much or stop this compass will just start spinning off in random directions).
This GPS lock may take some time (several minutes), and generally requires a clear view of the sky. The GPS can sometimes work indoors, but this isn't generally the case. Even a heavy tree canopy can interfere with GPS signal, and in large cities the tall buildings can block access to all but a few satellites, making a lock more difficult. So for best results, go outside and enjoy some fresh air while you wait for your first lock.
If you still don't get a GPS lock, there are several things that can be causing problems.

### GPS Setup

To verify that your GPS is set up properly on your BlackBerry:
* If you already use other third-party applications that use the GPS like Google Maps, and the GPS is working there, you can skip to "Security".
* Obviously, your phone needs to be set up with a GPS unit (sorry, Pearl users), and you need to allow third party applications to use it.
* This setup is generally found under Options - look for "Advanced Options" and "GPS".
** GPS Services must be set to "ON" or "Location ON". If you don't have the option to turn this on, you either don't have a GPS on board or your carrier has disabled it - contact your carrier for details or see the NOTE below.
* Try refreshing the GPS from this screen and see if you get a GPS lock (Menu Button, then select "Refresh GPS").
* For Blackberries that lack a GPS Receiver (like the Pearl) or cases where your carrier has disabled access to the GPS (Like Verizon OS 4.2) you need to use an external Bluetooth GPS receiver.
* If your GPS is not acquiring a lock after this, try a battery pull.
NOTE: Verizon (and probably other carriers) once had the GPS disabled for BlackBerry devices unless you purchased their Navigation software ($10/month). Verizon has supposedly removed this lock as of OS 4.5, so if you have a Verizon BlackBerry and you don't pay for TeleNav you'll need to upgrade the OS for BlackStar (or any third-party GPS application) to work with your internal GPS.

### Security

Your GPS may be working fine, but you also need to give BlackStar access to it. If you still can't see your location in BlackStar after verifying your GPS receiver works, check your application permissions and make sure BlackStar has access to "Location(GPS)" under "Connections".
From the "Options" menu, go to "Advanced Options" then "Applications". Menu-click on BlackStar and select "Edit Permissions". If necessary, use the spacebar to open the "Connections" section, and look for "Location(GPS)" and make sure that is set to "ALLOW".

## Adding/Managing Waypoints

Waypoints can generally be added in one of three ways:

### Entering Directly

From the BlackStar main screen, hit the menu key and select "New Waypoint". Enter a waypoint name, your desired Lat/Lon, and a description.
If obtaining Lat/Lon from geocaching.com, the data you need will be found by clicking the [Other Conversions] link next to the Lat/Lon degrees listed on the cache's main page. On the subsequent page under the heading "Older Datum (NAD27)" you'll use the data following DECIMAL. Which will be in the format XX.XXXX -XX.XXXXX

### Importing a GPX or LOC file from an SD card

If you don't have an SD card for your BlackBerry, get one. This is just another handy thing you can do with them.
GPX files are frequently used by Premium GeoCaching.com members to download lists of GeoCaches for "paperless" caching. You can have the GPX file emailed to your BlackBerry and save it to your SD card, or attach your BlackBerry to your desktop and copy it from there.
To import GPX files from the BlackStar main screen, hit [menu], select "List Waypoints", then select "Import GPX/LOC File". Find and select your GPX file and you're good to go.
Be careful with the sizes of these GPX files. While BlackStar seems to be able to handle a 500-cache query, every time you go to list the caches it'll try to sort them by distance, which means it has to calculate the distance for every cache in your current list. With 200 or more caches on board, this can be a significant wait.

### BCaching.com Import

BCaching.com also allows you to store Pocket Queries from Geocaching.com on their site if you are a Premium Geocaching member. You can even set the Pocket Queries to email directly to your BCaching.com account, meaning you always have a reasonably current list of GeoCaches "on tap" at your BCaching.com account. This is pretty easy to set up, and you can just create a few automated Pocket Queries that run every day or two and always have lots of current caches ready for "on the spur of the moment" GeoCaching.
You have to set up an account with BCaching (see their site for full details) and enter your BCaching credentials into BlackStar (under "Options" / "bcaching").
Once this is set up, BlackStar can pull the 20 Geocaches that are closest to your current position from BCaching. The real beauty of doing it this way is that the distance calculations are done on the BCaching site and are very fast. So if you keep your BlackStar waypoints list empty, BCaching can have your "nearest 20" loaded up and ready to go very quickly.
You have to have a GPS lock to load the nearest caches from BCaching. Once you have a lock, go to the Waypoints List and select "Get closest BCaching GPX". Wait for the "x caches added, x caches updated" message, exit the Waypoints List and go back in to force BlackStar to sort the new waypoints by distance.
Note: When you cache this way, you may find it helpful to clear your waypoints list every now and then. If you're driving around loading more and more caches into BlackStar, you'll find the distance calculations take longer and longer. 20 waypoints load almost instantly. 200 can take a frustrating amount of time.
Tip: If your Pocket Queries are set to exclude caches you've found, BCaching will have no way of taking them off the list of caches to find. Be sure your PQ includes found caches so BCaching is aware you've found the cache. (Personally, I use weekly queries to get new caches, and I have a daily query set up centered at my home coordinates that uploads only "caches I've found" within a 500-mile radius, emailed directly to my BCaching account - this marks caches I've found overnight so they don't show up the next day on BCaching).

## The Hunt

Now it's time to go find a GeoCache!

### Selecting a Waypoint

When you open the "list waypoints" screen, it will sort the waypoints by distance from you (if you have a GPS lock). It will also indicate the approximate direction of each cache.
The direction is based on your current heading (the direction you are currently moving), and not what direction your BlackBerry happens to be pointed. So if you're standing still, there's a very good chance the directions are going to be pretty much random. For best results, walk a little distance and make sure the compass indicator is showing your approximate direction of movement before loading up the waypoints screen.
There are several ways to decide which waypoint you want to find next. Click on one and select "Waypoint Details" to see the description of the Cache. You can also select "Show all on BBMaps" and you'll see your nearest waypoints on a map (assuming you have BlackBerry Maps installed).
Once you've picked the waypoint you want to go to, click on it and select "Set as Destination".

### Navigating to the Waypoint

The navigation screen will show you a compass rose with a red arrow pointing to the cache. As with all directional functions in BlackStar (and most GPS units, for that matter), this direction is interpolated from repeated readings of your location. In other words, if you stop moving, the BlackBerry has no way of knowing which way is "forward" and the arrow will likely start to spin around.
If you have to drive to the waypoint, or just prefer a map view, there are options on the main menu to see the waypoint in Google Maps or BlackBerry Maps.

### The Final Hunt

Once you reach the vicinity of the waypoint, there are several hunting tips to keep in mind:
* The arrow is (at the risk of sounding repetitive on this point) only accurate when you are moving in a straight line. If you stop or move in erratic directions, it becomes useless fast. You can counter this by using one of two techniques.
** Walk briskly in a straight line for at least 10 feet. This will calibrate the arrow for you.
** Ignore the arrow and look at the "distance to waypoint". If the number is getting smaller, you're headed in approximately the right direction.
* The BlackBerry, like all GPS units, is only accurate to about 3 meters or approximately 9 feet under ideal conditions. Tree canopy, large buildings, and even a heavy cloud cover can interfere with GPS signal reception and increase that error considerably. Also, the original coordinates may be off due to the same issues. So once you get to within about 20 feet or so, don't depend on the GPS as much.

### Found it!

Once you've found the cache, you can log it by selecting "Log Cache Online" from the menu. This will take you to the Geocaching.com mobile site with the log page for your cache preloaded. You may have to log in to Geocaching.com, of course.
This will not delete the cache from your GPX file or BCaching, so if you load your nearest from BCaching you'll see the same cache all over again. Keep track of what you've found for the day.

## Miscellaneous helpful hints
### GPS and battery life

The GPS is a very power-hungry device, and will drain your battery in a matter of hours. If you want your BlackBerry to live through a full day of caching, it's helpful to only run the GPS when you need it.
Once you know approximately where your GeoCache is, turn off BlackStar (and Google Maps or BBMaps) so the GPS can shut down for a while (unless you need it for navigation, of course). It's nice having an indicator that you are .9 miles from the cache.. .8... .7... etc., but shutting down the GPS until you really need it might mean the difference between finding the cache and running out of juice 200 feet from the cache.