coords — gpsd CLI for GPS coordinates (Decimal, DMS, UTM, MGRS)

Lightweight command‑line tool to read live GPS fixes from gpsd and print them in multiple formats: Decimal, Degrees‑Minutes‑Seconds (DMS), JSON, UTM, and MGRS.

Features

• Multiple formats: Display coordinates in decimal, DMS, JSON, UTM, or MGRS format
• Flexible monitoring: Single reading or continuous watching with customizable intervals
• 100% vibe coded: Because I have a Claude subscription, so why not use it?

Installation

Option A — pip (recommended)

# Install from local source (pyproject.toml)
pip install .

# Editable install for development
pip install -e .

# Or install directly from Git (replace with your repo URL)
pip install "git+https://github.com/kevinnord/coords.git"

Option B — Makefile (legacy/manual placement)

# Install to ~/.bin (default)
make install

# Or install to a custom directory
make install DEST="$HOME/.local/bin"

# Uninstall
make uninstall

Option C — Manual copy (offline fallback)

mkdir -p ~/.bin
cp coords ~/.bin/
cp -r coords-deps ~/.bin/
echo 'export PATH="$HOME/.bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
coords --help

Prerequisites

• gpsd: Must be running and connected to your GPS hardware
• Python 3.8+: Required for execution
• GPS hardware: A USB GPS dongle or equivalent

Usage

Basic Usage

# Show current coordinates (default: decimal format)
coords

# Get coordinates once and exit
coords --once

# Watch coordinates with default 10-second interval
coords --watch

# Watch coordinates with custom interval
coords --watch 30

Output Formats

# Decimal degrees (default)
coords --format decimal
# Output: LAT: 35.106353, LON: -78.874085

# Degrees, Minutes, Seconds
coords --format dms  
# Output: LAT: 35°6'22.87"N, LON: 78°52'26.71"W

# JSON
coords --format json
# Output: {"lat": 35.106353, "lon": -78.874085}

# UTM coordinates
coords --format utm
# Output: Zone: 17S, Easting: 693740, Northing: 3886907

# Military Grid Reference System
coords --format mgrs
# Output: 17SPU9374086907

Command Options

usage: coords [-h] [--format {decimal,dms,json,utm,mgrs}] [--once] [--watch [SECONDS]] [--version]

options:
  -h, --help            show this help message and exit
  --format {decimal,dms,json,utm,mgrs}
                        Output format (default: decimal)
  --once                Print one fix and exit
  --watch [SECONDS]     Continuously print fixes every SECONDS (default: 10, minimum: 1)
  --version             Show version and exit

Troubleshooting

• Error connecting to gpsd: Ensure gpsd is running and your device is added, e.g. sudo gpsd -N -D 2 /dev/ttyUSB0 -F /var/run/gpsd.sock.
• No fix available: You may be indoors or without sky view; try moving near a window or outside.
• MGRS/UTM formatting: These are provided by the bundled dependencies in coords-deps/ and work offline once installed.

Dependencies

When installed via pip, dependencies are resolved from PyPI:

• gpsd-py3 — Interface to gpsd daemon
• utm — Latitude/longitude to UTM conversion
• mgrs — Military Grid Reference System conversion

Offline/manual use: The repo includes coords-deps/ as a fallback for running directly from source or copying the script without pip. The packaged install does not include these vendored files.

Development

python -m venv .venv && source .venv/bin/activate
pip install -e .
coords --version

SEO Notes (Indexing)

• Keywords: gpsd, GPS coordinates, CLI, DMS, UTM, MGRS, latitude, longitude, geodesy, geospatial.
• Documentation: A minimal docs/ site is included to enable GitHub Pages for better indexing.
• Readme: Structured headings and keywords make this repository easier to discover.

License

GPL-3.0 — see LICENSE for details.