From 074806528f9760a3a9179913c662af6124a0dafc Mon Sep 17 00:00:00 2001
From: maze <maze@maze.io>
Date: Sun, 15 Mar 2026 21:38:09 +0100
Subject: [PATCH] Added README

---
 README.md | 118 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 118 insertions(+)

diff --git a/README.md b/README.md
index e69de29..121f541 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,118 @@
+# @hamradio/aprs
+
+APRS (Automatic Packet Reporting System) utilities and parsers for TypeScript/JavaScript.
+
+> For AX.25 frame parsing, see [@hamradio/ax25](https://www.npmjs.com/package/@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:
+
+```bash
+npm install @hamradio/aprs
+```
+
+Or with yarn:
+
+```bash
+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
+
+```ts
+import {
+	Frame,
+	Address,
+	Timestamp,
+	base91ToNumber,
+	knotsToKmh,
+} from '@hamradio/aprs';
+```
+
+### Parse a raw APRS frame and decode payload
+
+```ts
+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
+
+```ts
+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
+
+```ts
+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
+
+```ts
+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:
+
+```bash
+npm install
+npm test
+```
+
+Build the distribution with:
+
+```bash
+npm run build
+```
+
+## Contributing
+
+See the project repository for contribution guidelines and tests.
+
+---
+
+Project: @hamradio/aprs — APRS parsing utilities for TypeScript