navpoint/README.md

# Navpoint Desktop

Navpoint makes the user's current location available in KML format over
a local HTTP server (listening on `127.0.0.1`; external devices cannot
connect). Its main purpose is to allow GPS tracking from a digital globe
program such as [Google Earth Pro](https://www.google.com/earth/about).
(Navpoint is not developed or endorsed by Google.)

Navpoint makes the geographic data available in KML format at
`http://127.0.0.1:8888/navpoint.kml`. The `navpoint_link.kml` file in this
repository contains a link to this URL configured to update every three
seconds; simply open this file in Google Earth or another compatible program to
connect to Navpoint Desktop.

## Connection modes

Navpoint can obtain location information from two different sources. The first,
recommended where possible, is from a USB GPS receiver that supports the [NMEA
0183](https://en.wikipedia.org/wiki/NMEA_0183) protocol. (A handheld GPS
receiver connected to a computer may or may not work; it does not work with my
Garmin GPSMAP 64st. Any common USB GPS dongle, such as [this one available from
Amazon](https://www.amazon.com/VK-162-G-Mouse-External-Navigation-Raspberry/dp/B01EROIUEW/)
should work, although, of course, I cannot guarantee that any particular device
will be compatible with Navpoint. On Windows, USB mode should work
out-of-the-box with a compatible GPS receiver; on Linux, your user account
needs to be a member of the `dialout` group. If you get "Permission denied"
errors from Navpoint, run `sudo usermod -a -G dialout $USER`, then log out and
back in.

Alternatively, you may use the [Navpoint
Mobile](https://gallery.appinventor.mit.edu/?galleryid=2c18ee4d-4eed-452a-9228-de8e813820d1)
Android app. This uses an Android phone's GPS receiver to obtain location data;
however, it is typically less accurate than a USB module, and more likely to
have problems. Navpoint Desktop runs a second HTTP server listening on the
computer's local IP address (e.g. `192.168.x.x`), and the phone connects to
this server and sends location updates via HTTP requests. If you want to use
Navpoint Mobile, choose that option when opening Navpoint Desktop, then scan
the QR code from Navpoint Mobile. (Make sure that your phone and computer are
on the same Wi-Fi network, or that your phone's hotspot is on and your computer
is connected to it.)

## Licensing

Navpoint Desktop is released under the [GNU General Public License
v3.0](https://www.gnu.org/licenses/gpl-3.0.en.html), except the files
`navpoint/get_ip.py` and `navpoint/fix_path.py`, which are released under
[Creative Commons Attribution-ShareAlike 4.0
International](https://creativecommons.org/licenses/by-sa/4.0/) due to use of
code published on Stack Overflow
([`get_ip.py`](https://stackoverflow.com/a/28950776) and
[`fix_path.py`](https://stackoverflow.com/a/53605128)). 

Navpoint Mobile is released under the [GNU General Public License
v3.0](https://www.gnu.org/licenses/gpl-3.0.en.html).