@hamradio/aprs

APRS (Automatic Packet Reporting System) utilities and parsers for TypeScript/JavaScript.

For AX.25 frame parsing, see @hamradio/ax25.

This package provides lightweight parsing and helpers for APRS frames (APRS-IS style payloads). It exposes a small API for parsing frames, decoding payloads, working with APRS timestamps and addresses, and a few utility conversions.

Install

Using npm:

npm install @hamradio/aprs

Or with yarn:

yarn add @hamradio/aprs

Quick examples

Examples below show ESM / TypeScript usage. For CommonJS require() the same symbols are available from the package entrypoint.

Import

import {
	Frame,
	Address,
	Timestamp,
	base91ToNumber,
	knotsToKmh,
} from '@hamradio/aprs';

Parse a raw APRS frame and decode payload

const raw = 'NOCALL-1>APRS,WIDE1-1:@092345z/:*E";qZ=OMRC/A=088132Hello World!';

// Parse into a Frame instance
const frame = Frame.fromString(raw);

// Inspect routing and payload
console.log(frame.source.toString()); // e.g. NOCALL-1
console.log(frame.destination.toString()); // APRS
console.log(frame.path.map(p => p.toString()));

// Decode payload (returns a structured payload object or null)
const payload = frame.decode();
console.log(payload?.type); // e.g. 'position' | 'message' | 'status' | ...

// Or ask for sections (dissection) along with decoded payload
const res = frame.decode(true) as { payload: any | null; structure: any };
console.log(res.payload, res.structure);

Message decoding

const msg = 'W1AW>APRS::KB1ABC-5 :Hello World';
const f = Frame.fromString(msg);
const decoded = f.decode();
if (decoded && decoded.type === 'message') {
	console.log(decoded.addressee); // KB1ABC-5
	console.log(decoded.text); // Hello World
}

Work with addresses and timestamps

const a = Address.parse('WA1PLE-4*');
console.log(a.call, a.ssid, a.isRepeated);

const ts = new Timestamp(12, 45, 'HMS', { seconds: 30, zulu: true });
console.log(ts.toDate()); // JavaScript Date representing the timestamp

Utility conversions

console.log(base91ToNumber('!!!!')); // decode base91 values used in some APRS payloads
console.log(knotsToKmh(10)); // convert speed

API summary

• Frame — parse frames with Frame.fromString() / Frame.parse() and decode payloads with frame.decode().
• Address — helpers to parse and format APRS addresses: Address.parse() / Address.fromString().
• Timestamp — APRS timestamp wrapper with toDate() conversion.
• Utility functions: base91ToNumber, knotsToKmh, kmhToKnots, feetToMeters, metersToFeet, celsiusToFahrenheit, fahrenheitToCelsius.

Development

Run tests with:

npm install
npm test

Build the distribution with:

npm run build

Contributing

See the project repository for contribution guidelines and tests.

Project: @hamradio/aprs — APRS parsing utilities for TypeScript