Maptorium GPS Gate

USB/serial/TCP → TCP gateway for raw GPS NMEA data.

Repository: small TypeScript utility that reads raw NMEA sentences from a serial/USB/TCP GPS device and broadcasts them to any connected TCP client(s).

Files:

• Config: maptorium-gps-gate/config.js
• Gateway: maptorium-gps-gate/index.ts

Quick overview

• Supports two inlet modes:
  • serial (default): open a local USB/serial GPS device and use it as the data source.
  • tcp: connect to a remote TCP GPS server and use that stream as the data source.
• Starts a local TCP server and forwards every received raw byte chunk to all connected TCP clients.
• Multiple clients are supported; data is forwarded to every connected socket.

Requirements

• Node.js 18+ recommended
• Unix: permission to open the serial device (e.g. /dev/ttyAcm0) — adjust udev rules or run with appropriate permissions.

Install

cd maptorium-gps-gate
npm install

Configuration Edit maptorium-gps-gate/config.js to change device path, serial options, inlet mode and TCP settings. Example keys:

• inlet — 'serial' or 'tcp'. When 'serial' the gateway opens usb_device. When 'tcp' it connects to remote_host:remote_port as the data source.
• usb_device — serial device path (e.g. /dev/ttyAcm0 or COM3).
• options — serial port options, e.g. baudRate, dataBits, stopBits, parity.
• port — local TCP port to listen on for downstream clients.
• host — IP to bind (default 0.0.0.0).
• remote_host / remote_port — when inlet is tcp, connect to this remote server to receive NMEA.

Default config See the file: maptorium-gps-gate/config.js

Development Run the TypeScript file directly (fast iteration):

npm run dev

Build + Run (production)

npm run build
npm start

Connecting a TCP client You can use nc or telnet to test:

nc localhost 5000
# or
telnet localhost 5000

Any raw NMEA bytes received from the serial device will appear in the TCP client session.

Behavior & notes

• This gateway forwards raw bytes as received; it does not parse or alter NMEA sentences.
• If no TCP clients are connected the bytes are read but not buffered — they are discarded (no persistent replay). -- Serial disconnect/reconnect behavior: the gateway logs serial errors. Automatic reconnect is not implemented in the current version.
• When inlet is tcp the gateway connects to the configured remote server and forwards received bytes to local clients.
• The gateway will automatically attempt to reconnect to the remote TCP inlet every 5000 ms by default when the connection drops. You can change this delay with remote_reconnect_ms in config.js.

Troubleshooting

• Permission denied opening /dev/ttyAcm0: add your user to the dialout (or equivalent) group or create a udev rule.
• Wrong device path on Linux: find the device via ls /dev/tty* after plugging the GPS/USB.
• If the TCP server fails to start, ensure the configured port is free and the host binding is correct.

Dependencies

• serialport — low-level serial port access

Example topologies

• Single-network (USB host): run with inlet: 'serial' and other devices connect directly to this instance's TCP server.
• Two-network (bridge): run one instance with inlet: 'serial' on network A; run another instance on network B with inlet: 'tcp' pointing to network A instance; local clients on network B connect to the second instance's TCP server.

License & Contact MIT-ish (same as the project). For questions contact the author in the repository.