Version: | 2.1.0 |
Stand: | 2019-09-19T20:32:39Z |
Status: | Veröffentlicht |
Autor: | hebi63@hebinet.de |
Quelle: | gsak2poi-Installationsanleitung.md.pp |
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 eigenen, lokalen Sqlite3-Datenbank(en).
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 leider keine .ggz-Dateien sondern nur nur .gpx-Dateien verarbeiten kann und damit 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.
gsak2poi erstellt aus einer GSAK Datenbank die Datei Geocaches.gpi.
Diese Datei muss anschließend (manuell!) in das POI-Verzeichnis auf dem Garmin®-Gerät kopiert werden, sonst war die ganze Mühe umsonst.
Über eine im gsak2poi Ausgabeverzeichnis liegende Verknüpfung (_Start gsak2poi.lnk) wird ein kleines Programm (gsak2poi.exe) gestartet, das wiederum mittels Java das eingebettete Programm (gsak2poi.jar) zur Ausführung bringt. Dieses besorgt (unter Umgehung von GSAK) den Export der Geocaches und Wegpunkte aus der gewünschten (oder zuletzt von GSAK benutzten) GSAK-Datenbank in eine temporäre Struktur von .gpx-Dateien. Falls sich im static-Ordner des Ausgabeverzeichnisses weitere .gpx-Dateien und gleichnamige Bitmaps (.bmp) befinden, werden auch diese berücksichtigt. Nun werden noch die Bitmaps für noch fehlende Symbole beigelegt und das Ganze dem im Programm enthaltenen GPI-Generator zum Bauen der Geocaches.gpi-Datei übergeben.
Im Abschnitt Parametrisierung wird darauf eingegangen, wie sich dieser Ablauf ggf. ändern lässt.
So kann für die Generierung alternativ auch der Garmin® POI Loader verwendet werden, die zuverwendende GSAK-Datenbank, ein anderes Ausgabeverzeichnis, ein anderer Name für die zu erzeugende .gpi-Datei und weiteres mehr angepasst werden.
Die fertige Datei ist anschließend manuell in das POI-Verzeichnis auf dem Garmin®-Gerät zu kopieren.
Name | Version | Download-Link |
---|---|---|
GSAK | 9.0.0.14 | https://gsak.net/counter/?file=GSAK9FINAL.exe |
gsak2poi | 2.1.0 | https://hebinet.de/hebi63/gsak2poi/2.1.0/setup_gsak2poi.exe |
optional: | ||
Garmin® POI Loader | 2.7.3 | https://download.garmin.com/software/POILoaderforWindows_273.exe |
Damit du gsak2poi erfolgreich einsetzen kannst, müssen einige Voraussetzungen erfüllt sein:
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.
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 nennenswert 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 in 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…
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]
Seit der Version 2.0.0 wird Cygwin von gsak2poi nicht mehr benötigt.
Falls du Cygwin nur wegen gsak2poi der Version 1.x.x installiert hattest, könntest du es also wieder von deinem Computer entfernen.
Wie das geht wird u.a. hier beschrieben.
Seit der Version 2.0.0 wird Saxonica SaxonHE-N von gsak2poi nicht mehr benötigt.
Du kannst es also getrost wieder deinstallieren, falls du es nicht aus anderen Gründen benötigst.
Seit der Version 2.0.0 wird der Garmin® POI Loader von gsak2poi nicht mehr zwingend benötigt.
Falls du ihn dennoch verwenden möchtest, 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.
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.
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.
Das Programm steht dir zur freien, unentgeltlichen Nutzung unter dieser Lizenz zur Verfügung:
Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0)
Natürlich wurde nicht alles von mir selbst entwickelt, weshalb gsak2poi einige Software enthält, die nicht aus meiner Feder stammt. Die folgenden Unterabschnitte listen diese Softwarebestandteile auf.
In gsak2poi ist das Java Runtime Environment Adopt OpenJRE8 inetgriert. Dieses steht unter der Lizenz GPL v2 with Classpath Exception.
Zum Generieren einer .gpi-Datei wurde in gsak2poi das von Lukas Gebauer entwickelte Programm gpigen-1.2.0 integriert, welches von ihm unter die Lizenz Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0) gestellt wurde.
Von der Apache® Software Foundation werden im Apache Commons™-Projekt dankenswerterweise viele nützliche Java Bibliotheken bereitgestellt. Diese unterliegen der Apache License, Version 2.0.
Innerhalb von gsak2poi werden folgende Bibliotheken aus diesem Fundus verwendet:
- commons-beanutils-1.9.4
- commons-cli-1.4
- commons-collections4-4.4
- commons-configuration2-2.5
- commons-lang3-3.9
- commons-logging-1.2
- commons-text-1.7
Die Open-Source-Programmierschnittstelle dom4j wurde für den Zugriff und die Verarbeitung von XML-Dokumenten in Java entwickelt.
Innerhalb von gsak2poi wird dom4j-2.1.1 verwendet, welches einer BSD-Lizenz unterliegt.
Der von xerial entwickelte JDBC Treiber zum Zugriff auf Sqlite3-Datenbanken unterliegt ebenfalls der Apache License, Version 2.0.
Da gsak2poi vernünftigerweise nur auf Windows-Systemen eingesetzt werden kann, habe ich die Nicht-Windows-Komponenten allerdings aus sqlite-jdbc-3.27.2.1 entfernt.
Mittels Launch4j wird aus dem Java Programm eine normale
unter Windows ausführbare Datei gsak2poi.exe erzeugt, welche alle benötigten Komponenten bündelt.
Launch4j unterliegt der BSD 3-Clause License.
IExpress ist ein seit Windows 2000 in allen Windows-Systemen enthaltenes Tool zur Erstellung selbst-extrahierender Archive und kleinerer Installationsprogramme.
Das Programm setup_gsak2poi.exe wurde damit erstellt.
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.
Als Ausgabeverzeichnis wurde %USERPROFILE%\gsak2poi eingerichtet. Dort findest du die Verknüpfung _Start gsak2poi, mit welcher du gsak2poi starten kannst.
Ebenso wird sich ein Ordner static im Ausgabeverzeichnis finden, der für deine zusätzlich aufzunehmenden Wegpunkte bzw. Kartensymbole gedacht ist.
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.exe
gsak2poi.ico
Zur Erläuterung:
Das bin-Verzeichnis enthält das Programm und das Programm-Symbol.
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.
Du kannst dir beliebig viele Kopien der Programmverknüpfung _Start gsak2poi anlegen und diese bearbeiten (rechte Maustaste -> Eigenschaften). Im Feld Ziel kannst du nun den Programmaufruf um die von dir gewünschten Parameter ergänzen.
Standardmäßig liest gsak2poi die Daten aus der zuletzt von GSAK verwendeten Datenbank. Falls du nur eine Datenbank verwendest, wird deren Name wahrscheinlich Default
sein.
Du kannst gsak2poi aber auch anweisen, unabhängig davon, eine andere Datenbank zu verwenden.
Ergänze den Programmaufruf dann mit --database=<DB-Name>
.
Alternativ kannst du auch angeben -d <DB-Name>
.
Standardmäßig erzeugt gsak2poi eine Datei namens Geocaches.gpi.
Du kannst gsak2poi aber auch anweisen, einen anderen Dateinamen zu verwenden.
Ergänze den Programmaufruf dann mit --gpi-file=<Dateiname>
.
Alternativ kannst du auch angeben -g <Dateiname>
.
Standardmäßig sucht gsak2poi die als Kartensymbol verwendeten .bmp-Dateien unter dem Namen der jeweiligen .gpx-Datei in dieser Reihenfolge:
- im static-Ordner des Ausgabeverzeichnisses,
- im Icon-Set 0 von gsak2poi.
Derzeit verfügt gsak2poi über diese Icon-Sets:
Nr. | Größe | Design |
---|---|---|
0 | 16x16 | ähnelt den von GSAK verwendeten Icons |
1 | 24x24 | ähnelt denen der Geocaching App |
Es ist geplant, gsak2poi um weitere Icon-Sets zu ergänzen, die dann eine entsprechende Nummer erhalten. Mochtest du ein solches alternatives Icon-Set verwenden, kannst du den Paramter --icon-set angeben.
Ergänze den Programmaufruf dann mit --icon-set=<Nr. des Icon-Sets>
.
Alternativ kannst du auch angeben -i <Nr. des Icon-Sets>
.
Die Reihenfolge der Suche ändert sich dann folgendermaßen:
- im static-Ordner des Ausgabeverzeichnisses,
- im Icon-Set <Nr. des Icon-Sets> von gsak2poi,
- im Icon-Set 0 von gsak2poi.
Standardmäßig erzeugt gsak2poi die Ausgabedatei in seinem Standard-Ausgabeordner %USERPROFILE%\gsak2poi.
Du kannst gsak2poi aber auch anweisen, ein anderes Verzeichnis zu verwenden.
Ergänze den Programmaufruf dann mit --out-dir=<Verzeichnis>
.
Alternativ kannst du auch angeben -o <Verzeichnis>
.
Achtung: Der static-Ordner wird immer im angegebenen Ausgabe-Ordner gesucht!
Standardmäßig verarbeitet gsak2poi alle in der verwendeten GSAK-Datenbank gespeicherten Caches, und zwar unabhängig von deren Entfernung zur in der GSAK-Datenbank gespeicherten Homelocation.
Du kannst die Entfernung aber begrenzen, wenn du einen Radius (ganzzahlig, in km) angibst.
Ergänze den Programmaufruf dann mit --radius=<Radius>
.
Alternativ kannst du auch angeben -r <Radius>
.
Standardmäßig benutzt gsak2poi das Hilfsprogramm gpigen um aus .gpx-Dateien eine .gpi-Datei zu bauen
.
Diese Programm bringt gsak2poi gleich mit und muss daher auch nicht separat installiert werden.
Du kannst gsak2poi aber auch anweisen, statt dessen den Garmin® POI Loader zu verwenden, wenn du ihn denn installiert haben solltest.
Ergänze den Programmaufruf dann mit --use-poil.
Alternativ kannst du auch angeben -p.
Hinweis:
Falls du den Garmin® POI Loader verwendest, wird dieser 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 Garmin® POI Loaders. Erst dann geht es weiter!
Standardmäßig legt gsak2poi die Haupkategorie Zusätzliches an, die die zusätzlichen POIs aus im static-Ordner enthaltenen .gpx-Dateien sowie die Extra-Kategorien (siehe Parameter --extra) aufnimmt.
Du kannst diese aber auch anders benennen.
Ergänze den Programmaufruf dann mit --supplement=<Name der Hauptkategorie>
.
Alternativ kannst du auch angeben -s <Name der Hauptkategorie>
.
Standardmäßig separiert gsak2poi als gefunden
geloggte Caches unter der Rubrik GC Found
sowie deine eigenen Caches unter der Rubrik GC Found
extra ab und führt diese unter der Haupkategorie Zusätzliches (siehe Parameter --supplement).
Dieses Verhalten entspricht der Angabe --extra=FP
. Du kannst aber bei Bedarf noch weitere Unterkategorien bilden, die mit folgenden Kennbuchstaben gekennzeichnet werden:
Kennbuchstabe | Name der Kategorie | Beschreibung |
---|---|---|
D | GC DNF | Geocaches, die du zwar schon einmal gesucht aber nicht gefunden hast und deshalb ein DNF-Log verfasst hast. Vielleicht möchtest du diese ja gezielt ansteuern, um den aufgehängten Sackendlich in ein Smilie zu verwandeln. |
F | GC Found | Die bereits gefundenen Caches. |
P | GC Placed | Deine eigenen Caches. |
S | GC Solved | Caches mit geänderten Koordinaten, die du vielleicht nur noch abholenmöchtest. |
Ergänze den Programmaufruf dann mit --extra=<Liste der Kennbuchstaben>
.
Alternativ kannst du auch angeben -x <Liste der Kennbuchstaben>
.
Beispiel:
Du hast kein Interesse daran, die schon gefundenen Caches auf der Navi-Karte zu sehen, möchtest aber deine eigenen und gelösten gezielt ansteuern. Die DNFs ärgern dich auch nur auf der Karte und sollen wie andere ungesuchte Caches behandelt werden.
Dann setze diesen Parameter: --extra=PS
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.
Wenn du gsak2poi ohne weitere Parameter gestartet hattest, enthält die fertige Geocaches.gpi folgende Point of Interest
:
Userflagmarkiert hast
Watchedmarkiert hast
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:
Hauptkategorie | Unterkategorie | Bedeutung |
---|---|---|
Geocaches | GC <Cachetyp> | alle nicht gefundenen Geocaches des entsprechenden Typs mit eigenem Symbol |
Geocaching-Events | GC <Cachetyp> | alle nicht besuchten Events des entsprechende Typs mit eigenem Symbol |
Parkplätze | PK Parking Area | alle Parkplätze mit P-Schild als Symbol |
Wegpunkte | WP <WP-Typ> | alle Unterwegpunte des entsprechenden Typs mit eigenem Symbol |
Zusätzliches | GC Found | alle von dir gefundenen Caches, unabhängig von deren Typ, mit einem Smilie als Symbol |
GC Placed | alle von dir gelegten Caches, unabhängig von deren Typ, mit einem Stern als Symbol | |
<static-Name> | alle im static-Ordner abgelegten .gpx-Dateien mit dem gleichnamigen .bmp-Symbol |
Leere Hauptkategorien werden nicht angezeigt und Unterkategorien werden nur angezeigt, wenn es mehr als eine in der entsprechenden Hauptkategorie geben sollte.
So wird i.A. die Unterkategorie PK Parking Area
nicht als solche angezeigt werden, stattdessen werden die enthaltenen POIs direkt in der Hauptkategorie Parkplätze
erscheinen.
Keine Software ist fehlerfrei und mglw. hat es seit der Version 2.1.0 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/gsak2poi.
Änderungen:
- Überarbeitung der Symbole im Icon-Set 0 für die Kartendarstellung
- Überarbeitung der Symbole im Icon-Set 1 für die Kartendarstellung
- neuer Parameter –supplement - neuer Parameter –extra
Änderungen:
- vollständige Neuimplementierung mit Java
- dadurch deutlich weniger Installationsaufwand und obendrein schneller
- standardmäßige Nutzung von gpigen-1.2.0 statt dem Garmin® POI Loader
- gsak2poi speichert keine Log-Dateien mehr
- Überarbeitung der Symbole im Icon-Set 0 für die Kartendarstellung
Bugfixes:
- Sichern/Wiederherstellen der Registry-Werte mit save/restore wurde ersetzt durch get/set
Änderungen:
- Einführung von Hauptkategorien in der POI-Struktur
bekannte Fehler:
- Sichern/Wiederherstellen der Registry-Werte mit save/restore scheitert an unzureichenden Berechtigungen