Skip to content

Latest commit

 

History

History
303 lines (201 loc) · 17.8 KB

getting-started.md

File metadata and controls

303 lines (201 loc) · 17.8 KB

Getting Started with OpenSAK

OpenSAK (Open Source Swiss Army Knife) is a free, open-source geocache management tool for Windows, Linux, and macOS. It lets you import, organise, filter, and navigate your geocache collection — all offline, without needing a Geocaching.com subscription beyond your normal account.

Coming from GSAK? OpenSAK uses the same GPX/Pocket Query workflow you already know. Jump to Importing Your Caches to get started quickly.


Table of Contents

  1. Installation
  2. First Launch
  3. Importing Your Caches
  4. Understanding the Interface
  5. Filtering Your Cache List
  6. Cache Details and Hints
  7. Waypoints
  8. Marking Caches as Found
  9. Updating Finds from "My Finds"
  10. Exporting to GPS
  11. Multiple Databases
  12. Changing the Language
  13. Getting Help

1. Installation

  • Windows — install OpenSAK from the Microsoft Store. It's free, signed by Microsoft and keeps itself up to date. A direct download (ZIP) is also available.
  • macOS — download the .dmg for your Mac (Apple Silicon or Intel) from the Releases page, open it and drag OpenSAK to Applications. The app is signed and notarized, so it opens normally.
  • Linux — download the AppImage from the Releases page, make it executable (chmod +x OpenSAK-*.AppImage) and run it. On first launch it offers to add itself to your application menu.

See Installation for all options, how updating works, and how to uninstall.


2. First Launch

The first time you start OpenSAK, the Welcome Wizard walks you through a few steps:

  1. Installation folder — where OpenSAK keeps its settings and log file. The default is fine for most people.
  2. Database folder — where your geocache databases are stored. Choose a different folder here if you want your databases somewhere specific (e.g. a folder you back up). If the folder already holds OpenSAK databases — after a reinstall or on a new computer — the wizard lists them and offers to add them; untick any you don't want.
  3. Backup folder — where OpenSAK keeps its backups, by default Documents/OpenSAK Backups. A folder on another disk, an external drive or a synced folder is safest, because it also protects your data if your computer's disk fails.
  4. Your Geocaching profile — optional; you can also set this later in Settings.

After the wizard you'll see OpenSAK's three-panel layout: the cache list, the cache details and the map — all empty until you import some caches.

Before importing, it's a good idea to set your home point. It is used as the centre for distance calculations and the map.

  1. Go to Settings → Settings… (Ctrl+,)
  2. In the User locations section, add your home coordinates — any common format works (e.g. N55 47.250 E012 25.000 or 55.7875, 12.4167)
  3. Click Save

You can save several named home points (Home, Cottage, Hotel…) and switch between them from the toolbar.


3. Importing Your Caches

OpenSAK works with standard GPX files and Pocket Query ZIP files — the same files you already download from Geocaching.com.

Downloading a Pocket Query (recommended)

  1. Log in to geocaching.com
  2. Go to Play → Pocket Queries
  3. Create or run an existing Pocket Query
  4. Download the .zip file — do not unzip it

Importing into OpenSAK

  1. Click File → Import GPX / PQ zip… (or press Ctrl+I)
  2. Select your .zip or .gpx file
  3. Click Open — OpenSAK will import all caches and their logs

Tip: You can import multiple files into the same database. Duplicate caches are updated automatically, so you can re-import an updated Pocket Query without creating duplicates.

Auto-geocoding: After a successful import, OpenSAK automatically runs an offline lookup to fill in the county, state, and country for any waypoints that are missing that data. No extra step needed. For higher-accuracy results you can run an optional online refinement afterwards — see Waypoints.

Pocket Queries by e-mail

If your Pocket Queries arrive by e-mail, OpenSAK can fetch them straight from your mailbox. Set up the mailbox under Settings → Settings… → PQ Email, then use File → Check for PQ Email…. The password is kept in your operating system's keyring, never in plain text.

Coming from GSAK

You can import a GSAK database directly with File → Import from GSAK Database… — including personal notes, corrected coordinates, child waypoints, attributes and the full log history. Point it at a GSAK backup .zip to see every database in the backup and import the ones you pick, each as its own OpenSAK database. The same import also turns your saved GSAK filters, views and user locations (from gsak.db3) into OpenSAK filter profiles, column views and home locations — pick a backup, or gsak.db3 on its own if you only want those. OpenSAK also uses the same GPX/PQ format as GSAK, so your Pocket Queries import as usual.


4. Understanding the Interface

OpenSAK uses a three-panel layout:

┌─────────────────────────────────────────────┐
│             Cache List (top)                │
│  GC Code │ Name │ Type │ D/T │ Distance ... │
├───────────────────────┬─────────────────────┤
│   Cache Details       │       Map           │
│   (bottom-left)       │   (bottom-right)    │
└───────────────────────┴─────────────────────┘

Cache List

  • Click any column header to sort
  • Right-click a cache for quick actions: Open on geocaching.com, Copy coordinates, Mark as found
  • Choose which columns to show via View → Choose columns… — save a set of columns as a named column view there, or bring your GSAK views over with File → Import from GSAK Database… (tick Also import the saved GSAK views). A GSAK column OpenSAK has no column for is left out and listed after the import; a custom-field column is kept and shows in every database that has that field.

Cache Details

Shows the full description, hint (click to decode ROT13), attributes, and logs for the selected cache.

  • Click the GC code to open the cache page in your browser
  • Click the coordinates to open them in your preferred map app (Google Maps or OpenStreetMap — set in Settings)

Map

Shows all caches in the current list as colour-coded pins, clustered when zoomed out. Click any pin to highlight that cache in the list and show its details. Use View → Maximize map or Pop out map for a bigger view.

Right-click anywhere on the map to copy that spot's coordinates (or set them as the selected cache's corrected coordinates). With the ✎ button you can draw a polygon, a line or points and use the shape in the Line/Polygon filter.


5. Filtering Your Cache List

Filters let you narrow down the cache list to exactly what you want to see. The filter dialog is modelled on GSAK's and has ten tabs — General, Dates, Other, Logs, Line/Polygon, Child Waypoints, Trackables, Attributes, Text Search and Where — all combinable with AND/OR logic, plus a global Invert filter. See the Filter Reference for every filter.

Opening the Filter Dialog

Click View → Set filter… (or press Ctrl+F).

Common filter examples

Goal Filter to use
Only unfound caches Found = No
Difficulty 1–2 only Difficulty ≤ 2
Within 5 km of home Other tab: Distance from centre point, At most 5 km
Traditional caches only Cache type = Traditional
Caches with parking nearby Attributes includes Parking
Not yet attempted (no DNF) DNF = No

Saving a Filter Profile

Once you have set up a useful combination of filters, save it as a profile:

  1. Configure your filters
  2. Click Save and give the profile a name (e.g. "Easy day trip")
  3. Pick it any time from the filter profile dropdown in the toolbar

Clearing Filters

Click the red ✕ in the toolbar, or View → Clear filter, to show all caches again.


6. Cache Details and Hints

Click any cache in the list to see its full details in the bottom-left panel.

  • Description — full HTML cache description
  • Hint — click the hint text to toggle ROT13 decoding
  • Attributes — icons showing cache features (dog friendly, available 24/7, etc.)
  • Logs — recent logs from other cachers; use the search box to find specific entries

7. Waypoints

Waypoints are additional coordinates associated with a cache — parking spots, stages for multi-caches, final coordinates, etc.

Viewing Waypoints

Waypoints imported from GPX/PQ files appear automatically in the cache details panel and as extra pins on the map.

Adding a Waypoint Manually

  1. Select a cache in the list
  2. Open Waypoint → Edit cache… (Ctrl+E) and go to the Waypoints tab
  3. Click Add waypoint…, and enter the prefix, type, name and coordinates
  4. Click OK

For solved mystery caches, use corrected coordinates instead (right-click the cache → corrected coordinates): the original coordinates are kept, and the corrected ones are used on the map and when exporting to GPS.

Updating Location Data (county, state, country)

OpenSAK can fill in the county, state, and country fields for waypoints using reverse geocoding.

  • On import — the offline lookup runs automatically for any waypoints missing location data.
  • Manually — go to Waypoint → Update waypoint locations… to re-run or refine the lookup for some or all caches.

The offline lookup uses the bundled GeoNames database and works with no internet connection. An optional online refinement pass (using OpenStreetMap polygon data) is available for higher accuracy — it is opt-in because it is rate-limited and can be slow on large databases.

For full details, see Update Waypoint Locations.


8. Marking Caches as Found

Marking a Single Cache

Right-click the cache in the list → Mark as Found.

Importing Finds from Geocaching.com (recommended)

For the most accurate found status, use a My Finds Pocket Query — see the next section.


9. Updating Finds from "My Finds"

For the most accurate found status across all your databases, use a My Finds Pocket Query from Geocaching.com.

  1. On geocaching.com, go to Play → Pocket Queries
  2. Find the My Finds query and download it as a .zip file
  3. In OpenSAK, create a new database called "My Finds" (File → Manage databases…)
  4. Import the My Finds ZIP into that database
  5. Switch back to the database you want to update
  6. Go to Settings → Update finds from reference database… and select the "My Finds" database

OpenSAK will mark all matching caches as found, even caches that are not in the current database.


10. Exporting to GPS

OpenSAK can export your filtered cache list directly to a Garmin GPS device connected via USB.

  1. Filter the cache list to the caches you want on the GPS — the export uses the caches currently in the list
  2. Connect your Garmin device
  3. Click Settings → Send to GPS… (or press Ctrl+G)
  4. Click Scan to detect your device, and make sure Send directly to GPS device is selected
  5. Optionally limit the number of caches (0 = all)
  6. Click Send to GPS

The caches are written as a GPX or GGZ file to your Garmin's Garmin/GPX/ folder. Newer Garmin models that connect over MTP instead of as a USB drive are supported on Windows and Linux. Bluetooth transfer is not currently available.

To save a file instead — for another GPS app, a phone or a friend — use File → Export (GPX/LOC/GGZ). Set a folder and a file name once (the file name can use variables such as {database}_{date}), and later exports go straight there; save the settings under a name if you export the same way often.


11. Multiple Databases

OpenSAK supports multiple separate databases — useful if you geocache in different regions or want to keep work and leisure caches separate.

Creating a New Database

  1. Go to File → Manage databases… (Ctrl+D)
  2. Click New database…
  3. Give it a name — and, if you like, choose a different folder for it
  4. Click OK — the new database becomes the active one
  5. Set the home location for that region (see First Launch); each database remembers its own

Adding Databases You Already Have

Click Open existing… in File → Manage databases… to add one database file, or Scan database folder… to see every OpenSAK database in your database folder that isn't in the list yet and add the ones you tick. OpenSAK never adds databases by itself, so one you removed from the list stays removed until you add it again.

Switching Between Databases

Use the database dropdown in the toolbar, or go to File → Manage databases… and double-click a database.

Each database has its own:

  • Cache list and import history
  • Home location for distance calculations
  • Column layout and sort order
  • Last-used filter profile

These are stored inside the database file, so they stay with the database when you copy, move, rename or restore it. Saved filter profiles themselves are shared by all databases.

Copying and Moving a Database

In File → Manage databases…, Copy… makes a copy under a new name and Move… moves a database to another folder under the same name — for example from a USB stick to your internal disk. Both let you choose the folder and never overwrite an existing file. Move only deletes the original once the copy has been checked.

If the database you used last is on a drive that isn't connected when you start OpenSAK, OpenSAK opens another database from your list and tells you which one was missing. The missing one stays in the list, so you can switch back when the drive is connected again.

Backing Up

Go to File → Back up now… to back up your databases together with your settings, filter profiles, column views and custom icons. Backups go into the backup folder you chose in the Welcome Wizard (by default Documents/OpenSAK Backups); change it under Settings → Advanced → Folders or in the backup dialog itself. A folder on another disk or an external drive is safest. Existing backups stay where they are when you change the folder. Backups you make this way are never deleted by OpenSAK. To save space, turn on Compress backups under Settings → Advanced → Backups: new backups are then one zip file, usually a third or less of the size, but they take longer to make.

When a new version of OpenSAK needs to update a database to a new format, it first saves an untouched copy of it (in the pre-migration folder of your backup folder) and tells you where. If other databases in your list are from the older version too, Apply to all databases updates them all in one go.

When you close OpenSAK and something has changed since your last backup, OpenSAK asks whether to back up first: Back Up and Close, Not Now, or Cancel to stay in OpenSAK. Tick Don't ask again to always back up or never ask; change it later, together with how many automatic backups to keep (5 by default), under Settings → Advanced → Backups. Only the oldest automatic backups are deleted.

Restoring a Backup

Go to File → Restore from backup…, pick a backup and the databases you want, and click Restore. A restored database is always added as a new database — nothing you have now is overwritten — and it opens exactly as it was when the backup was taken. Tick Also restore settings to bring back your preferences, filter profiles, column views and icons as well; they take effect the next time OpenSAK starts, and your current settings are saved first as a backup marked Settings before restore.


12. Changing the Language

  1. Go to Settings → Settings…
  2. Select your language in the Language section
  3. Restart OpenSAK — the new language takes effect on next startup

Currently supported (11): Danish, English, French, Dutch, Portuguese, German, Swiss German, Czech, Swedish, Polish and Spanish

Want to add a new language? See CONTRIBUTING.md for the step-by-step guide — it only requires translating one file.


13. Getting Help

Found a bug or have a feature request? → github.com/OpenSAK-Org/opensak/issues

Questions and community discussion? → OpenSAK Facebook Group

Full user guide? → opensak.com/user-guide.html

Latest releases and downloads? → github.com/OpenSAK-Org/opensak/releases

Full changelog? → CHANGELOG.md


OpenSAK is free and open-source software, released under the MIT licence. Contributions are welcome — see CONTRIBUTING.md for details.

Last updated for v1.21.0.