[RFC] feat: add external GPS source support for tethered devices

[BlackBoxEngineering]

Description

This PR adds support for external GPS sources to the Meshtastic web client, enabling desktop users without GPS hardware to use GPS from tethered mobile devices via USB. This is particularly useful for desktop users who want to use Meshtastic mesh networking but don't have built-in GPS.

The implementation provides a flexible multi-source GPS architecture with automatic fallback between browser geolocation, Android devices (via ADB), and iOS devices.

Note: This is a Draft PR to gather feedback on the approach before completing documentation and i18n work.

Related Issues

N/A - This is a new feature enhancement

Changes Made

• Added GPS page with multi-source GPS architecture and toggle controls
• Implemented GPS service with automatic fallback between multiple sources
• Added GPS bridge service for reading Android GPS via ADB over USB
• Added browser geolocation support as primary GPS source
• Added localStorage persistence for GPS source preferences
• Added visual indicators showing which GPS sources are connected and active
• Added instructions for setting up external GPS bridges
• Only show external GPS options when bridges are detected
• Added GPS route and navigation menu item

Testing Done

• Tested browser geolocation on desktop (Chrome, Firefox)
• Tested Android GPS via ADB bridge with USB-connected device
• Verified toggle switches enable/disable GPS sources correctly
• Verified localStorage persistence across page refreshes
• Tested GPS data updates every 30 seconds
• Verified fallback behavior when sources are unavailable
• Tested on Windows desktop without GPS hardware

Screenshots (if applicable)

(Will add screenshots showing GPS page UI)

Checklist

• Code follows project style guidelines
• Documentation has been updated or added (Will add GPS bridge setup guide based on feedback)
• Tests have been added or updated (Manual testing completed, can add automated tests if needed)
• All i18n translation labels have been added (Will add i18n keys based on feedback)

Additional Notes

Setup Instructions for External GPS:
Users who want to use external GPS need to:

1. Run node gps-bridge-service.js in a separate terminal
2. Ensure Android device is connected via USB with ADB enabled
3. The GPS page will automatically detect the bridge and show toggle options

Questions for Reviewers:

• Is the multi-source GPS architecture acceptable?
• Should the GPS bridge be included in the monorepo or documented separately?
• Any preferences for i18n key naming conventions?
• Should this feature be behind a feature flag initially?

[vercel]

@BlackBoxEngineering is attempting to deploy a commit to the Meshtastic Team on Vercel.

A member of the Team first needs to authorize it.

[CLAassistant]

All committers have signed the CLA.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[danditomaso]

I get the idea of this PR but the approach will need to be tweaked, for local development and self hosting using Docker it makes sense, but all code needs to run either in Docker or from our prod Vercel site.

[danditomaso]

I get what you're trying to accomplish here, but any solution like this must use the following:

• Written in TypeScript
• Be able to operate both locally on a users machine (dev mode, or running in a docker container)
• Also work within our hosting platform (Vercel) without any firewall tricks required by the user.

[BlackBoxEngineering]

I get what you're trying to accomplish here, but any solution like this must use the following:

• Written in TypeScript
• Be able to operate both locally on a users machine (dev mode, or running in a docker container)
• Also work within our hosting platform (Vercel) without any firewall tricks required by the user.

Vercel
Uses browser Geolocation API only - No bridge no Firewall config needed

Local Dev
Users can optionally run node gps-bridge-service.ts separately
Only for desktop users without GPS hardware
Not required for the web app to function

The web app detects if the bridge is available (checks http://localhost:8080/gps) and falls back to browser geolocation if not. Vercel deployment works with browser GPS, Local browser GPS OR the optional bridge

The bridge is purely an optional local development tool.

[danditomaso]

Why? This script duplicates the line above.

[danditomaso]

I'm unclear why this library was added when its not being used in the npm scripts?

[BlackBoxEngineering]

I'll could refactor the GPS bridge service to TypeScript and implement and environment-aware function that works both locally and on Vercel. For local development and Docker, it will use the ADB GPS polling service, while for production deployment on Vercel, it will fall back to browser geolocation APIs without requiring any firewall configuration.

I'll could also utilize the concurrently dependency properly by updating the dev script to run both the Vite server and bridge services simultaneously. I can remove the duplicate dev:web-only

This might then deploy on the hosting platform. I have no GPS on my browser.

[danditomaso]

As well have you reviewed the Geolocaiton API that all browsers widely support? https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API

[BlackBoxEngineering]

As well have you reviewed the Geolocaiton API that all browsers widely support? https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API

Changes Made:
Converted gps-bridge-service.js to TypeScript with proper type definitions
Removed concurrently dependency (not needed)
Removed duplicate dev:web-only script

Re: Geolocation API
Yes! The implementation already uses the browser Geolocation API as the primary GPS source. You can see this in gpsService.ts:

if (navigator.geolocation) {
  this.watchId = navigator.geolocation.watchPosition(
    (position) => {
      if (localStorage.getItem('gps-browser') === 'false') return;
      if (!this.position) {
        this.position = position;
        logger.debug('GPS: Using browser geolocation');
      }
    },
    // ... error handling
  );
}