1 Motivation

Ich nutze bereits seit vielen Jahren auf meinem Windows-Laptop das Programm GSAK (Geocachers Swiss Army Knife) zur Verwaltung meiner Caches.
Dieses Programm nutzt die Geocaching-Live-API zur Abfrage der Geocache-Daten aus der Datenbank von Groundspeak (geocaching.com) und speichert diese Daten in einer eigenen, lokalen Sqlite3-Datenbank.

Neben hervorragenden Möglichkeiten, in dieser lokalen Datenbank allerhand Recherchen anstellen zu können, eigene Notizen und zusätzliche Wegpunkte einzubringen sowie einer schier unermesslich scheinenden Anzahl von zusätzlich installierbaren Makros (die mal mehr, manchmal auch weniger nützlich sind), bietet die Software aber auch Schnittstellen zu diversen GPS-Geräten.

Dazu exportiert GSAK die vorab mittels Filterfunktion ausgewählten Geocaches nebst ihrer Unterwegpunkte entweder im GPX- oder im moderneren GGZ-Format auf das per USB-Kabel mit dem Computer verbundene GPS-Gerät. Eine absolut unschätzbare Funktionalität!

Das funtioniert grundsätzlich zwar auch mit meinem Fahrzeug-Navi von Garmin (nüvi 2xxx), hat aber den Haken, dass dieses nur GPX-Dateien verarbeiten kann und hier auch nur eine sehr begrenzte Anzahl von Wegpunkten. Obendrein werden alle Caches unabhängig von ihrem Typ nur mit einem Einheitssymbol (geschlossene oder geöffnete Schatzkiste) dargestellt.

Viel besser wäre es, die Geocaches und Wegpunkte als Points of Interest (POI) ins Navi zu laden. Deren Anzahl ist nämlich (nahezu) unbegrenzt. Außerdem könnten die verschiedenen Geocache- und Wegpunkt-Typen jeweils eine eigene POI-Kategorie darstellen, für die wiederum ein eigenes Symbol hinterlegt werden kann.

Leider bietet keines der für GSAK verfügbaren Makros eine befriedigende Lösung für mein Ansinnen. Das mag unter anderem daran liegen, dass Garmin bisher keine Spezifikation seines GPI-Formats veröffentlicht hat. Es wurde lediglich beschrieben, wie die Daten zu gestalten sind, die dem Garmin POI Loader vorgelegt werden können, um eine GPI-Datei zu erzeugen. Das ließe sich ja mittels GSAK-Makro vielleicht noch bewerkstelligen, benötigt aber so viel Zeit, dass mir bald die Lust daran vergangen ist.

Deshalb habe ich gsak2poi entwickelt.

2 Zweck und Arbeitsweise von gsak2poi

2.1 Kurzfassung

gsak2poi erstellt aus der Default-Datenbank von GSAK unter Zuhilfenahme einiger Tools (s.a. benötigte Software) eine Geocaches.gpi Datei.
Diese Datei muss (manuell!) in das POI-Verzeichnis auf dem Garmin-Gerät kopiert werden, sonst war die ganze Mühe umsonst.

2.2 etwas detallierter (nur für daran Interessierte)

Über eine im gsak2poi Ausgabeverzeichnis Verknüpfung (_Start gsak2poi.lnk) wird ein kleines Command-Script (gsak2poi.cmd) gestartet, das wiederum mittels Cygwin das eigentliche Bash-Script (gsak2poi.sh) zur Ausführung bringt. Dieses besorgt (unter Umgehung von GSAK) mittels sqlite3 den Export der Geocaches und Wegpunkte aus der GSAK-Default-Datenbank in eine HTML-Datei. Diese wird dann durch Saxon-HE gemäß einer Transformationsvorschrift (gsak2poi.xsl) zerlegt und in verschiedene GPX-Dateien überführt. Nun werden noch die Bitmaps für die benötigten Symbole beigelegt und das Ganze dem Garmin POI Loader zum Bauen der Geocaches.gpi-Datei übergeben.
Die fertige Datei ist anschließend manuell in das POI-Verzeichnis auf dem Garmin-Gerät zu kopieren.

3 Bezugsquellen für die benötigte Software

4 Voraussetzungen

Damit du gsak2poi erfolgreich einsetzen kannst, müssen einige Voraussetzungen erfüllt sein:

• Du nutzt Windwos 7 (oder höher) als Betriebssystem auf deinem Computer.
• Du nutzt ein Straßennavigationsgerät von Garmin, dass GPI-Dateien verarbeiten kann (z.B. Garmin nüvi, Garmin Drive).
• Du bist Member bei geocaching.com.
• Du hast GSAK installiert (und auch schon Caches in dessen Datenbank gespeichert).
• Du hast Cygwin incl. der benötigten Erweiterungen installiert.
• Du hast Saxonica SaxonHE-N installiert.
• Du hast den Garmin POI Loader installiert.

Falls du weder Windows nutzt, noch ein Garmin Navi für die Straße, brauchst du gar nicht erst weiterlesen.
Der Rest lässt sich (auch mit dieser Anleitung) lösen.

4.1 Wie installiere ich GSAK?

Lade dir die Software unter Nutzung des in den Bezugsquellen angegebenen Download-Links aus dem Internet herunter.
Übrigens seit Version 9.0.0.0 (Stand Mai 2019) ist die Software für jedermann frei nutzbar. Leider wird sie seitdem aber auch nicht mehr weiterentwickelt.

Die Installation an sich ist selbsterklärend, folge einfach den Anweisungen des Installationsprogramms.

Beim ersten Start wird dir angeboten, Beispiel-Caches in die Datenbank zu laden. Darauf kannst du verzichten.
Ebenso öffnet sich das Hilfe-Fenster von GSAK, was wir im Moment auch nicht brauchen und deshalb schließen.
Die GSAK-Tipps sind zwar gelegentlich nützlich, mich persönlich stören sie aber, weshalb ich den Haken bei Tipps beim Start anzeigen rausgenommen habe.

Ist dein Computer über einen Proxy an das Internet angebunden, erreichst du über das Menü Extras -> Optionen auf der Registerkarte Erweitert -> Seite 2 den Abschnitt Proxy-Server, um die notwendigen Angaben zu machen.

Die GSAK-Datenbank ist noch leer und so natürlich nicht zu gebrauchen. Um sie mit Caches von geocaching.com zu befüllen, musst du GSAK mit deinem GC-Account bei der Geocaching-Live-API akkreditieren.
Klicke also im Menü auf: Geocaching.com-Zugriff -> Neues Zugriffstoken abrufen. Du wirst ein einem kleinen Fenster um deine Login-Daten gebeten und musst anschliessend der Nutzung von geocaching.com durch GSAK zustimmen.
Damit GSAK auch intern weiß, wer du bist und wo deine Homezone liegt, klickst du im Menü auf Geocaching.com-Zugriff -> Benutzerinformationen aktualisieren.
Anschließend setzt du über Zentrum -> Homelocaction das Zentrum auf genau eben das: deine Homelocation.

Damit ist GSAK grundsätzlich bereit, Caches abzurufen. Versuch es mal mit den Caches in deiner unmittelbaren Homezone und klicke auf Geocaching.com-Zugriff -> Geocaches abrufen…

4.2 Wozu brauche ich Cygwin?

Mit Cygwin lassen sich Computerprogramme, die üblicherweise unter POSIX-Systemen wie GNU/Linux, BSD und Unix laufen, auf das Betriebssystem Windows von Microsoft portieren. Es ist eine Kompatibilitätsschicht, die die Unix-API für verschiedene Versionen von Windows zur Verfügung stellt, auf deren Basis eine Vielzahl von Programmen aus der Unix-Welt unter Windows übersetzt werden kann. [Quelle: Wikipedia]

Um es kurz zu machen: Hauptsächlich benötige ich das Cygwin-System wegen seiner Bash-Shell, die mir (im Gegensatz zu Microsofts cmd- oder PowerShell) eine sehr mächtige und effiziente Script-Sprache bietet. Ebenso nutze ich für gsak2poi ein paar Cygwin-Erweiterungen. Außerdem kann Cygwin besser mit dem UTF-8 Zeichensatz umgehen, als Windows dies tut. Aber so was langweilt dich sicher…

4.3 Installation des Cygwin-Systems

Richte auf deiner Festplatte ein leeres Repository-Verzeichnis für Cygwin ein, z.B. C:\Cygwin_Repository.

Lade dir unter Nutzung des in den Bezugsquellen angegebenen Download-Links das zu deiner Betriebssystem-Version passende Cygwin-Setup-Programm (32-bit bzw. 64-bit) aus dem Internet herunter und speichere es in diesem Repository-Verzeichnis. Wechsle in das Verzeichnis und starte von dort das Setup-Programm.

Auf dem angezeigten Splash-Screen sollte etwas von Cygwin Net Release Setup Program stehen sowie die Versionsnummer des Setup-Programms Setup version 2.897 (?? bit). Ist die Versionsnummer inzwischen höher, ist das auch in Ordnung.

Im nächsten Schritt wählst du die Option Install from Internet und klickst wieder auf Weiter.

Das Root Directory kannst du wie vorgeschlagen übernehmen oder nach Geschmack ändern. Dann geht es Weiter.

Als Local Package Directory trägst du bitte dein Repository-Verzeichnis ein. Hier liegt ja schon das Setup-Programm und im weiteren Verlauf werden hier auch die vom Setup-Programm gedownloadeten Pakete abgelegt. Weiter geht’s.

Im Regelfall wirst du mit der Standardeinstellung Use System Proxy Settings bzw. Direct Connection für deine Internetverbindung richtig liegen. Falls du jedoch nur über einen bestimmten Proxy Server ins Internet kommen solltest, musst du hier die entsprechenden Angaben machen.

Wähle nun aus der Liste einen möglichst flott an das Internet angebundenen Server aus. Das weiß natürlich kein Mensch. Bei mir hat sich aber http://ftp-stud.hs-esslingen.de ganz gut bewährt.

Nachdem du auf Weiter geklickt hast, startet der Download des Paket-Angebots vom ausgewählten Server. Das kann je nach Internetverbindung schon mal ein Weilchen dauern.

Anschließend wird im View Category eine aufklappbare Liste der Paket-Kategorien angezeigt. Klicke auf [+] All, um sie aufzuklappen. Alle Kategorien werden unter der Spaltenüberschrift New mit dem Vermerk Default geführt. Das reicht ohne weitere Änderungen auch für ein grundlegendes Cygwin-Sytem aus. Wir werden zwar noch ein paar Erweiterungen brauchen, doch damit beschäftigen wir uns später. Also frisch auf den Weiter-Button geklickt!

Im nächsten Schritt Review and confirm changes betrachten wir ehrführchtig die Liste und bestätigen wohlwollend mit Weiter.

Jetzt wird das Cygwin-System mit allem bestückt, was wir zuvor ausgewählt hatten. Ggf. werden dazu auch weitere Paket aus dem Internet nachgeladen. Was natürlich wieder etwas dauert und entweder zu einer gemütlichen Tasse Kaffee einlädt oder aber man genießt einfach das Mäusekino aus drei mehr oder weniger zappelnden Balken.

Anschließend wird dir noch angeboten, ein Desktop-Icon anzulegen sowie einen Eintrag im Startmenü. Das solltest du tun, auch falls du später selber mit Cygwin arbeiten willst. Wenigsten den Startmenü-Eintrag solltest du aber machen.

Damit ist die grundhafte Installation erst einmal abgeschlossen und du kannst auf Fertig stellen klicken.

Jetzt starte bitte über das Windows-Startmenü das Cygwin-Terminal, damit deine Arbeitsumgebung eingerichtet werden kann. Denn beim ersten Start werden noch ein paar Dateien in dein Home-Verzeichnis des Cygwin-Systems kopiert.

Eine gute Gelegenheit zu prüfen, was noch nachinstalliert werden muss, damit später gsak2poi auch seinen Job machen kann. Dazu gibst du folgenden Befehl in die Console ein:

cygcheck -c bash bc gawk sqlite3 vim

Idealerweise bekommst du folgende Ausgabe:

Cygwin Package Information
Package              Version        Status
bash                 4.4.12-3       OK
bc                   1.06.95-2      OK
gawk                 5.0.1-1        OK
sqlite3              3.28.0-1       OK
vim                  8.1.1772-1     OK

Fehlt eines der Pakete, liegt in einer zu niedrigen Version vor oder ist gar beschädigt, notierst du dir bitte dessen Namen oder merkst ihn dir.

Mit dem Befehl logout verlässt du das Cygwin-System wieder. (Tipp: Es geht auch kürzer, indem du Strg-D auf deiner Tastatur drückst.)

Falls auf deine Liste der fehlenden bzw. upzudatenden Cygwin-Pakete (noch) nicht leer ist, startest du jetzt erneut das Setup-Programm von Cygwin (zur Erinnerung: dieses befindet sich in deinem Cygwin-Repository-Verzeichnis).
Da wir an den Basiseinstellungen nichts ändern wollen, klickst du immer wieder auf Weiter, bis du auf der Seite Select Packages angekommen bist. Dort wechselst du jetzt vom View Pending (die Liste sollte leer sein) in den View Full.

In das Feld Search gibst du jetzt einen der Namen von deiner Liste ein, um die angezeigten Pakete einzugrenzen. Nun suchst du die Zeile mit deinem Paketnamen in der Spalte Package. In der Spalte Current wird dir die Versionsnummer des aktuell installierten Pakets angezeigt bzw. keine, falls es noch gar nicht installiert wurde. Jetzt klickst du auf die Schaltfläche mit dem kleinen, nach unten gerichteten Pfeil am rechten Rand der Spalte New und wählst die gewünschte Version des Paketes aus der Liste aus.

Diesen Schritt wiederholst du, bis du alle Paketnamen auf deinem Merkzettel abgearbeitet hast.

Nachdem du auf Weiter geklickt hast, wird die noch einmal auf der Review and confirm changes-Seite eine Zusammenfassung der nächsten Operationen angezeigt, die du natürlich mit Weiter bestätigen musst.

Es folgt das schon bekannte Mäusekino und das erneute Angebot, ein Desktop-Icon und einen Startmenü-Eintrag anzulegen. Falls du die schon hast (oder immer noch nicht willst), brauchst du die Haken nicht erneut zu setzen. Entfernt werden die dadurch nämlich nicht!

Noch ein Klick auf Fertigstellen und du kannst erneut das Cygwin-Terminal starten und mit cygchek prüfen, ob jetzt alles da ist, was gebraucht wird.

4.4 Installation Saxonica SaxonHE-N

Lade dir das in den Bezugsquellen angegebene Programm SaxonHE9-9-1-4N-setup.exe aus dem Internet herunter und starte es. Die weiteren Schritte sind selbsterklärend.

4.5 Installation Garmin POI Loader

Lade dir das in den Bezugsquellen angegebenen Programm POILoaderforWindows_273.exe aus dem Internet herunter und starte es. Die weiteren Schritte sind wieder selbsterklärend.
Zum Ende der Installation wird dir automatisch ein Start des POI Loaders angeboten, was du auch tun solltest, selbst wenn du noch gar nichts hast, was dem POI Loader zur Verarbeitung angeboten werden könnte. Denn beim ersten Start werden ein paar Einträge in die Windows Registry geschrieben, die gsak2poi später noch brauchen wird. Klicke einfach auf Abbrechen und alles ist gut.

5 Einrichten von gsak2poi auf deinem Computer

5.1 Lizenzhinweis

Das Programm gsak2poi wurde von hebi63 entwickelt, damit du es leichter hast, deine in GSAK gespeicherten Geocaches in eine für ein POI-fähiges GARMIN Straßennavigations-Gerät geeignete Datei zu überführen.

Es steht dir zur freien, unentgeltlichen Nutzung zur Verfügung.

Fehler sind nie auszuschließen, deshalb verwendest du dieses Programm grundsätzlich auf eigene Gefahr!
Der Entwickler haftet also auf keinen Fall für Schäden jedweder Art.

Falls du einen Fehler entdeckst, Wünsche oder Anregungen hast, kannst du dich aber gern per Mail an hebi63@hebinet.de wenden.

5.2 Download und Setup

Sind alle Voraussetzungen gegeben, kannst du von meiner Webseite das Programm setup_gsak2poi.exe herunter laden und starten, um gsak2poi zu installieren.

Großartige Wahlmöglichkeiten lässt es dir freilich nicht, aber am Ende sollten sich die benötigten Dateien auf deinem Rechner befinden.

Tipp: Das Setup-Programm von gsak2poi hat dir auf deinem Desktop eine Verknüpfung auf den gsak2poi Ausgabeordner angelegt und auch dein Startmenü unter der Rubrik gsak2poi um einige Einträge bereichert.

5.3 Sichtung des gsak2poi Ausgabeordners

Als Ausgabeverzeichnis wurde %USERPROFILE%\gsak2poi eingerichtet. Dort findest du die Verknüpfung _Start gsak2poi, mit welcher du gsak2poi starten kannst.

5.4 Sichtung des gsak2poi Programmverzeichnisses

Wenn du mit dem Windows-Explorer in das Verzeichnis %LOCALAPPDATA%\gsak2poi wechselst bzw. in einem cmd-Fenster das Kommando
tree %LOCALAPPDATA%\gsak2poi /f eingibst, solltest du folgende Strukturen und Dateien vorfinden:

│
│   gsak2poi_license.txt
│   gsak2poi-Installationsanleitung.html
│
├───bin
│       gsak2poi.cmd
│       gsak2poi.ico
│       gsak2poi.sh
│       gsak2poi.xsl
│
├───bmp
│       GC Cache In Trash Out Event.bmp
│       GC Earthcache.bmp
│       GC Event Cache.bmp
│       GC Found.bmp
│       GC Giga-Event Cache.bmp
│       GC Lab Cache.bmp
│       GC Letterbox Hybrid.bmp
│       GC Mega-Event Cache.bmp
│       GC Multi-cache.bmp
│       GC Other.bmp
│       GC Placed.bmp
│       GC Traditional Cache.bmp
│       GC Unknown Cache.bmp
│       GC Virtual Cache.bmp
│       GC Webcam Cache.bmp
│       GC Wherigo Cache.bmp
│       WP Final Location.bmp
│       WP Parking Area.bmp
│       WP Physical Stage.bmp
│       WP Question to Answer.bmp
│       WP Reference Point.bmp
│       WP Stages of a Multicache.bmp
│       WP Trailhead.bmp
│       WP Virtual Stage.bmp
│
└───log

Zur Erläuterung:
Das bin-Verzeichnis enthält die Script-Dateien,
das bmp-Verzeichnis die Bitmap-Symbole für die verschiedenen Geocache- und Wegpunkt-Typen.
Das log-Verzeichnis ist wahrscheinlich noch leer und dient zur Speicherung der Logdateien, die gsak2poi bei jedem Aufruf anlegt. gsak2poi sorgt auch dafür, dass dieses Verzeichnis nicht vollläuft und löscht nach jedem Lauf die Logdateien, welche älter als sieben Tage sind.

6 Starten von gsak2poi

Ab jetzt ist alles ein Kinderspiel: Öffne den gsak2poi Ausgabeordner und klicke auf die Programmverknüpfung _Start gsak2poi.
Es öffnet sich ein Consolen-Fenster, in dem du den Fortschritt der Arbeiten verfolgen kannst.
Nach kurzer Zeit sollte deine Geocaches.gpi-Datei fertig sein und zur Übertragung an dein GARMIN Navi bereit stehen.

Hinweis:
Der Garmin POI Loader wird von gsak2poi in einem seperaten Prozess gestartet und meldet sich erst am Ende seiner Tätigkeit mit einer Meldung. Das Dumme dabei ist, dass diese Meldung manchmal hinter anderen Fenstern verborgen erscheint. Du musst diese Meldung aber unbedingt bestätigen, denn gsak2poi wartet auf die Beendigung des POI Loaders. Erst dann geht es weiter!

7 Wie kommt die Geocaches.gpi auf mein Navi?

Schließe dein Garmin Navi per USB an den Computer an. Kurze Zeit später sollte es im Windows Explorer unterhalb von Dieser PC angezeigt werden.
Öffne diesen Ordner und darin wiederum den Ordner Internal Storage.
Dort gibt es mglw. bereits einen Ordner POI. Falls nicht, musst du ihn neu anlegen.

Und in genau diesen Ordner Dieser PC->nüvi …->Internal Storage->POI musst du die fertige Geocaches.gpi kopieren.

8 Was ist am Ende in der Geocaches.gpi enthalten?

Wenn du gsak2poi ohne weitere Parameter gestartet hattest, enthält die fertige Geocaches.gpi folgende Point of Interest:

• alle aktiven Caches aus der GSAK-Default-Datenbank
• alle nicht archivierten Caches (aktiv+disabled), die du selbst gelegt hast
• alle nicht archivierten Caches (aktiv+disabled), die du mit einem Userflag markiert hast
• alle nicht archivierten Caches (aktiv+disabled), die du als Watched markiert hast
• die Unterwegpunkte der oben angeführten Caches
• alle Parkplätze unabhängig vom Status des jeweiligen Caches

Stets ausgenommen sind jedoch POIs, die an den Null-Kordinaten (N00° 00.000’ E000° 00.000’) liegen würden.
Mitten in den Atlantik fährst du wohl kaum mit deinem Auto und es schont den Rechner in deinem Navi enorm.

In deinem Navi werden dir diese Point of Interest, soweit vorhanden, unterteilt nach folgenden Kategorien angezeigt:

9 Updates von gsak2poi beziehen

Keine Software ist fehlerfrei und mglw. hat es inzwischen auch einige Verbesserungsvorschläge oder Änderungswünsche gegeben.

Eine aktuelle Version dieser Installationsanleitung (die ggf. auch den Link zu einer neueren Version von gsak2poi enthält) findest du im Internet unter https://hebinet.de/hebi63/gsak.poi.