This project includes:
- A small user-space "driver" for the Pharos GPS-360 receiver (
gps360/driver.py) - A user-space Apple Silicon PL2303 USB driver (
gps360/pl2303.py) - A terminal app that reads live GPS fixes (
gps360/app.py) - A local GUI app (raw NMEA + OpenStreetMap) (
gps360/web_app.py) - A USB-to-PTY bridge command (
gps360/usb_bridge.py)
It targets macOS on Apple Silicon and reads NMEA over a USB serial port (/dev/cu.*).
If no serial node is present, it can read directly from the Prolific USB device.
- App (Apple Silicon macOS): gps360-viewer-macos-apple-silicon-v0.3.0.zip
- App checksum: gps360-viewer-macos-apple-silicon-v0.3.0.zip.sha256
- Source bundle: gps360-source-v0.3.0.zip
- Source checksum: gps360-source-v0.3.0.zip.sha256
- Release page: v0.3.0
This codebase targets the same hardware family commonly sold/listed as:
PB010 iGPS-500Microsoft Pharos GPS-500PHAROS PB010 iGPS-500
Common USB identity for these dongles:
- Vendor ID:
0x067B(Prolific) - Product ID:
0xAAA0 - Typical USB product string:
USB-Serial Controller
Quick hardware reference: Pharos/Microsoft GPS-500 manual
Hardware photos (example unit):
Rear label view (example markings include
GPS-500 and SiRF III).
GPS360 Viewer.app can be shared with other Apple Silicon Macs (M1/M2/M3/M4) running macOS 13+.
Notes:
- The app bundle is relocatable and now embeds the
gps360Python module. - It is built as
arm64; Intel Macs are not supported. - Target machine needs Python 3 available at one of:
/opt/homebrew/bin/python3/usr/local/bin/python3/usr/bin/python3
- The app uses bundled
libusbwhen available; otherwise install it with Homebrew (brew install libusb). - OpenStreetMap tiles require internet access.
- The app is unsigned/not notarized by default.
If macOS says "GPS360 Viewer" is damaged and can't be opened after download:
- Open System Settings -> Privacy & Security
- Scroll to the Security section and click Open Anyway for
GPS360 Viewer - Confirm by clicking Open in the follow-up dialog
If needed, fallback terminal method:
xattr -dr com.apple.quarantine "/path/to/GPS360 Viewer.app"
codesign --force --deep --sign - "/path/to/GPS360 Viewer.app"
open "/path/to/GPS360 Viewer.app"To eliminate this for end users, sign with a Developer ID cert and notarize releases.
Build and package publishable artifacts:
./scripts/package_release.sh 0.3.0This generates:
dist/gps360-viewer-macos-apple-silicon-v0.3.0.zipdist/gps360-viewer-macos-apple-silicon-v0.3.0.zip.sha256dist/gps360-source-v0.3.0.zipdist/gps360-source-v0.3.0.zip.sha256
Run commands from the project root (Pharos Microsoft GPS-360 Receiver), not from the inner gps360/ folder.
If you are currently inside gps360/, either:
- run
cd ..first, or - prefix commands with
PYTHONPATH=..
- Build the Finder app:
./scripts/build_macos_app.shThen double-click GPS360 Viewer.app.
This opens a self-contained window (no terminal and no external browser window).
- Or use the bundled wrapper launcher:
./launch_gps360_gui.commandThis wrapper now just opens GPS360 Viewer.app.
- Debug mode (web server + browser) if needed:
python3 -m gps360.web_app --transport usb --open-browserIf you change source files, re-run ./scripts/build_macos_app.sh.
- Stop the GUI server if needed:
pkill -f "python3 -m gps360.web_app" || trueThe map panel pulls tiles from OpenStreetMap, so internet access is required for the right-side map.
The map uses an in-page renderer (Leaflet) to avoid iframe refresh flicker during live tracking.
aibzy-1qsp1.icns is used as the app icon when present (fallback: generated from logo.png).
The GUI now parses extra telemetry from GSA/GSV: fix type (No Fix/2D/3D), satellites in view, satellites used, DOP values, used PRNs, top SNR satellites, a fix-readiness indicator, and a live satellite sky-plot (azimuth/elevation).
Run commands from the project root (Pharos Microsoft GPS-360 Receiver), not from the inner gps360/ folder.
If you are currently inside gps360/, either:
- run
cd ..first, or - prefix commands with
PYTHONPATH=..
- List candidate serial ports:
python3 -m gps360.app --list-ports- Run (defaults to direct USB transport):
python3 -m gps360.app- Or run with an explicit port:
python3 -m gps360.app --port /dev/cu.usbserial-XXXXUse serial-first auto detect only when needed:
python3 -m gps360.app --transport auto- Optional: log fixes to JSON Lines:
python3 -m gps360.app --jsonl fixes.jsonl- Print raw NMEA sentences:
python3 -m gps360.app --raw- Create a virtual serial device from USB (PTY bridge):
python3 -m gps360.usb_bridgeThen use the printed /dev/ttys* path with serial tools or:
python3 -m gps360.app --port /dev/ttysXXXX- This code is a user-space driver. It does not install a kernel extension.
- Auto-detection only accepts ports that emit valid NMEA, so it avoids unrelated serial devices.
- The receiver must still appear as a serial device under
/dev/cu.*. - Default mode is
--transport usb, which uses a direct PL2303 user-space path vialibusb. - Use
--transport autofor serial-first detection with USB fallback. - Many GPS-360 units expose a USB-serial chipset (often PL2303 era hardware). If no serial port appears, you may need a macOS-compatible Apple Silicon USB-serial driver for that chipset.
- Some units boot in SiRF binary protocol; the USB-direct path sends a startup switch to NMEA automatically.
For CLI usage (python3 -m gps360.app) and source-only runs, libusb is required.
The packaged GPS360 Viewer.app bundles libusb when available at build time.
If your environment does not have libusb, install it:
brew install libusbTo inspect USB detection:
system_profiler SPUSBDataType | grep -Ei "pharos|prolific|pl2303|gps|serial" -B2 -A6If the app reports:
Prolific USB hardware is attached, but no matching /dev/cu.* serial interface is available
Then macOS sees the USB device, but does not have a usable serial endpoint for it yet. Default mode already uses USB-direct, so this is expected to still work.
- Run
./scripts/package_release.sh 0.3.0 - Push source files to GitHub (the
.gitignoreexcludes app/capture/build artifacts) - Create a GitHub Release and upload:
dist/gps360-viewer-macos-apple-silicon-v0.3.0.zipdist/gps360-viewer-macos-apple-silicon-v0.3.0.zip.sha256dist/gps360-source-v0.3.0.zipdist/gps360-source-v0.3.0.zip.sha256
- In release notes, mention required Python 3 and optional Homebrew
libusb
This project was generated and refined with OpenAI Codex assistance.
MIT, see LICENSE.
The parser currently handles:
GGA(position, fix quality, satellites, HDOP, altitude)RMC(status, position, speed, course, UTC date/time)
--port <path> Explicit serial port (example: /dev/cu.usbserial-XXXX)
--baud <rate> Baud rate (default: 4800)
--timeout <sec> Read timeout per cycle (default: 2.0)
--list-ports Print candidate serial ports and exit
--jsonl <file> Append fixes as JSON lines
--once Read and print one fix, then exit
--raw Print raw NMEA sentences (good for connectivity checks)
--transport <mode> `usb` (default), `auto`, or `serial`
--usb-vid <id> USB vendor ID for direct mode (default: 0x067B)
--usb-pid <id> USB product ID for direct mode (default: 0xAAA0)
--host <addr> Bind host for local web app (default: 127.0.0.1)
--port <port> Bind port for local web app (default: 8765)
--transport <mode> `usb` (default), `auto`, or `serial`
--serial-port <p> Explicit serial device for serial/auto mode
--baud <rate> Baud rate (default: 4800)
--usb-vid <id> USB vendor ID for direct mode (default: 0x067B)
--usb-pid <id> USB product ID for direct mode (default: 0xAAA0)
--open-browser Open GUI URL automatically
Use the engineering probe to test whether the receiver will switch into SiRF binary mode and to capture raw bytes:
python3 -m gps360.sirf_probe --duration 15Outputs are saved under captures/:
sirf-<timestamp>.binraw bytessirf-<timestamp>.jsondecoded summary
Interpretation:
- If
frame_count > 0, the dongle emitted SiRF binary frames and the summary includes decoded MID data. - If
frame_count == 0andwire_observation.likely_wire_protocol == "nmea_text", the device stayed in NMEA mode during probing.