@packet-net/pdn-aprs 0.0.1

package/src/deviceid.ts

@@ -0,0 +1,83 @@
+// Device identification from the APRS device identification database
+// (https://github.com/aprsorg/aprs-deviceid): by destination (tocall), or for a Mic-E report by
+// its type code and suffix.
+
+import { MICE, MICE_LEGACY, TOCALLS, type DeviceEntry } from './deviceid-data.js';
+import type { DeviceInfo } from './types.js';
+
+export { DEVICEID_SOURCE, DEVICE_CLASSES } from './deviceid-data.js';
+
+function toInfo(entry: DeviceEntry): DeviceInfo {
+  const out: { -readonly [K in keyof DeviceInfo]: DeviceInfo[K] } = {};
+  if (entry.vendor !== undefined) out.vendor = entry.vendor;
+  if (entry.model !== undefined) out.model = entry.model;
+  if (entry.class !== undefined) out.class = entry.class;
+  if (entry.os !== undefined) out.os = entry.os;
+  if (entry.features !== undefined) out.features = entry.features;
+  return out;
+}
+
+interface CompiledTocall {
+  regex: RegExp;
+  fixed: number;
+  length: number;
+  entry: DeviceEntry;
+}
+
+let compiled: CompiledTocall[] | undefined;
+
+function compile(): CompiledTocall[] {
+  if (compiled) return compiled;
+  compiled = TOCALLS.map((t) => {
+    let re = '';
+    let fixed = 0;
+    for (const c of t.tocall) {
+      if (c === '?') re += '.';
+      else if (c === '*') re += '.*';
+      else if (c === 'n') re += '[0-9]';
+      else {
+        re += c.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        fixed++;
+      }
+    }
+    return { regex: new RegExp(`^${re}$`), fixed, length: t.tocall.length, entry: t };
+  });
+  // Most specific first: more fixed characters, then longer patterns.
+  compiled.sort((a, b) => b.fixed - a.fixed || b.length - a.length);
+  return compiled;
+}
+
+/** The device a destination address (tocall) identifies, e.g. `APDW18` is Dire Wolf. */
+export function identifyTocall(destination: string): DeviceInfo | undefined {
+  const call = destination.split('-')[0]!.toUpperCase();
+  for (const t of compile()) if (t.regex.test(call)) return toInfo(t.entry);
+  return undefined;
+}
+
+/**
+ * The device suffix at the end of Mic-E status text, if the database knows one for this type
+ * code: a two-character suffix after `` ` `` or `'`, a one-character Kenwood suffix after `>` or `]`.
+ */
+export function findMicESuffix(typeCode: string, text: string): string | undefined {
+  if (typeCode === '`' || typeCode === "'") {
+    for (const m of MICE) if (text.endsWith(m.suffix)) return m.suffix;
+  } else if (typeCode === '>' || typeCode === ']') {
+    for (const m of MICE_LEGACY) if (m.prefix === typeCode && m.suffix !== undefined && text.endsWith(m.suffix)) return m.suffix;
+  }
+  return undefined;
+}
+
+/** The device a Mic-E type code and suffix identify. */
+export function identifyMicE(typeCode: string | undefined, suffix: string | undefined): DeviceInfo | undefined {
+  if (typeCode === undefined) return undefined;
+  if (typeCode === '`' || typeCode === "'") {
+    if (suffix === undefined) return undefined;
+    const m = MICE.find((e) => e.suffix === suffix);
+    return m ? toInfo(m) : undefined;
+  }
+  if (typeCode === '>' || typeCode === ']') {
+    const m = MICE_LEGACY.find((e) => e.prefix === typeCode && e.suffix === suffix);
+    return m ? toInfo(m) : undefined;
+  }
+  return undefined;
+}

package/src/diagnostics.ts

@@ -0,0 +1,86 @@
+import { DIAGNOSTIC_MEANINGS, isTolerable, TOLERABLE_CODES, type DiagnosticCode, type TolerableCode } from './codes.js';
+
+/** How serious a diagnostic is. */
+export type Severity = 'info' | 'warning' | 'error';
+
+/**
+ * Something the decoder noticed about a packet: a defect it tolerated (`warning`), one that
+ * stopped it (`error`), or a remark (`info`, e.g. an obsolete format).
+ */
+export interface Diagnostic {
+  readonly severity: Severity;
+  readonly code: DiagnosticCode;
+  /** A plain ASCII description. */
+  readonly message: string;
+}
+
+/** Makes a diagnostic with the standard description of its code. */
+export function diagnostic(severity: Severity, code: DiagnosticCode, detail?: string): Diagnostic {
+  const meaning = DIAGNOSTIC_MEANINGS[code];
+  return { severity, code, message: detail ? `${meaning} ${detail}` : meaning };
+}
+
+/** Formats a diagnostic as `severity:code`, the form the conformance vectors use. */
+export function formatDiagnostic(d: Diagnostic): string {
+  return `${d.severity}:${d.code}`;
+}
+
+/**
+ * Which defects the decoder tolerates. A lenient decoder (the default) tolerates every tolerable
+ * code, with a warning; a strict one tolerates none, and rejects a packet at the first defect.
+ * Each code can be switched on or off by itself.
+ *
+ * ```ts
+ * ParseOptions.lenient;                                  // the default
+ * ParseOptions.strict;
+ * ParseOptions.lenient.without('trailing-line-break');   // lenient, except for that one
+ * ParseOptions.strict.with('lowercase-hemisphere');      // strict, except for that one
+ * ```
+ */
+export class ParseOptions {
+  /** Tolerates every tolerable defect, with a warning. */
+  static readonly lenient: ParseOptions = new ParseOptions(new Set(TOLERABLE_CODES));
+  /** Tolerates nothing. */
+  static readonly strict: ParseOptions = new ParseOptions(new Set());
+
+  private readonly tolerated: ReadonlySet<TolerableCode>;
+
+  private constructor(tolerated: ReadonlySet<TolerableCode>) {
+    this.tolerated = tolerated;
+  }
+
+  /** Options that tolerate exactly these codes. */
+  static tolerating(codes: Iterable<TolerableCode>): ParseOptions {
+    const set = new Set<TolerableCode>();
+    for (const code of codes) {
+      if (!isTolerable(code)) throw new RangeError(`${String(code)} is not a tolerable code`);
+      set.add(code);
+    }
+    return new ParseOptions(set);
+  }
+
+  /** These options, also tolerating `code`. */
+  with(code: TolerableCode): ParseOptions {
+    if (!isTolerable(code)) throw new RangeError(`${String(code)} is not a tolerable code`);
+    const set = new Set(this.tolerated);
+    set.add(code);
+    return new ParseOptions(set);
+  }
+
+  /** These options, no longer tolerating `code`. */
+  without(code: TolerableCode): ParseOptions {
+    const set = new Set(this.tolerated);
+    set.delete(code);
+    return new ParseOptions(set);
+  }
+
+  /** Whether `code` is tolerated. */
+  tolerates(code: DiagnosticCode): boolean {
+    return this.tolerated.has(code as TolerableCode);
+  }
+
+  /** The tolerated codes. */
+  get toleratedCodes(): readonly TolerableCode[] {
+    return [...this.tolerated];
+  }
+}

package/src/encode/common.ts

@@ -0,0 +1,87 @@
+// Shared pieces of the encoder.
+
+import { encodeUtf8Binary } from '../bytes.js';
+import type { AprsSymbol, AprsTimestamp } from '../types.js';
+
+/** Thrown when the encoder declines to write something the spec does not allow; says why. */
+export class AprsEncodeError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'AprsEncodeError';
+  }
+}
+
+export function refuse(reason: string): never {
+  throw new AprsEncodeError(reason);
+}
+
+export function pad(n: number, width: number): string {
+  return String(n).padStart(width, '0');
+}
+
+/** A whole number within [min, max], else refused. */
+export function whole(value: number, min: number, max: number, what: string): number {
+  if (!Number.isFinite(value)) refuse(`${what} is not a number`);
+  const n = Math.round(value);
+  if (n < min || n > max) refuse(`${what} ${value} is out of range (${min}-${max})`);
+  return n;
+}
+
+/** Free text as UTF-8 bytes (a binary string); refuses a line break, which receivers strip. */
+export function freeText(text: string, what: string): string {
+  if (/[\r\n]/.test(text)) refuse(`${what} contains a line break`);
+  return encodeUtf8Binary(text);
+}
+
+export function isValidTimestamp(t: AprsTimestamp): boolean {
+  const ok = (v: number, lo: number, hi: number): boolean => Number.isInteger(v) && v >= lo && v <= hi;
+  switch (t.kind) {
+    case 'dhm-zulu':
+    case 'dhm-local':
+      return ok(t.day, 1, 31) && ok(t.hour, 0, 23) && ok(t.minute, 0, 59);
+    case 'hms':
+      return ok(t.hour, 0, 23) && ok(t.minute, 0, 59) && ok(t.second, 0, 59);
+    case 'mdhm':
+      return ok(t.month, 1, 12) && ok(t.day, 1, 31) && ok(t.hour, 0, 23) && ok(t.minute, 0, 59);
+  }
+}
+
+/** A 7-byte timestamp for a position or object report. */
+export function timestamp7(t: AprsTimestamp): string {
+  if (!isValidTimestamp(t)) refuse('the timestamp is out of range');
+  switch (t.kind) {
+    case 'dhm-zulu':
+      return `${pad(t.day, 2)}${pad(t.hour, 2)}${pad(t.minute, 2)}z`;
+    case 'dhm-local':
+      return `${pad(t.day, 2)}${pad(t.hour, 2)}${pad(t.minute, 2)}/`;
+    case 'hms':
+      return `${pad(t.hour, 2)}${pad(t.minute, 2)}${pad(t.second, 2)}h`;
+    case 'mdhm':
+      return refuse('a month/day/hour/minute timestamp is only for positionless weather reports');
+  }
+}
+
+export function checkSymbol(symbol: AprsSymbol): void {
+  if (symbol.code.length !== 1 || symbol.table.length !== 1) refuse('a symbol is a table and a code, one character each');
+  const code = symbol.code.charCodeAt(0);
+  if (code < 0x21 || code > 0x7e) refuse('the symbol code is not printable ASCII');
+  const t = symbol.table;
+  const ok = t === '/' || t === '\\' || (t >= '0' && t <= '9') || (t >= 'A' && t <= 'Z');
+  if (!ok) refuse(`the symbol table ${JSON.stringify(t)} is not /, \\, 0-9 or A-Z`);
+}
+
+export function base91(value: number, width: number): string {
+  let v = value;
+  let out = '';
+  for (let i = 0; i < width; i++) {
+    out = String.fromCharCode((v % 91) + 33) + out;
+    v = Math.floor(v / 91);
+  }
+  return out;
+}
+
+/** Formats a number as short text: `0.53`, `-32`, `1e-7`. */
+export function numberText(v: number): string {
+  if (!Number.isFinite(v)) refuse('a value is not a number');
+  return String(v);
+}

package/src/encode/index.ts

@@ -0,0 +1,280 @@
+// The encoder: writes only what the spec allows and refuses anything else with a reason. Free
+// text is checked by decoding what was written: if the result does not read back as the same
+// data (a comment that would read as an altitude, say), a `/` delimiter is tried, and if that
+// does not help either the encoder refuses.
+
+import { binaryToBytes, bytesToBinary, decodeUtf8 } from '../bytes.js';
+import { decodeInformation } from '../decode/index.js';
+import { formatDiagnostic, ParseOptions } from '../diagnostics.js';
+import { isAprsIsAddress } from '../header.js';
+import { toNeutralData } from '../neutral.js';
+import type { AprsData, CompressionType, PathEntry } from '../types.js';
+import { AprsEncodeError, refuse } from './common.js';
+import {
+  encodeAck,
+  encodeAgrelo,
+  encodeBulletin,
+  encodeCapabilities,
+  encodeDirectedQuery,
+  encodeMaidenhead,
+  encodeMessage,
+  encodeNmea,
+  encodeQuery,
+  encodeRawWeather,
+  encodeStatus,
+  encodeTelemetryBits,
+  encodeTelemetryCoefficients,
+  encodeTelemetryNames,
+  encodeTelemetryReport,
+  encodeTest,
+  encodeThirdParty,
+  encodeUserDefined,
+} from './other.js';
+import { encodeItem, encodeMicE, encodeObject, encodePositionReport, encodeWeatherReport, type CommentMode } from './position.js';
+
+export { AprsEncodeError } from './common.js';
+
+/** An encoded information field, and for Mic-E the destination address it needs. */
+export interface EncodedInformation {
+  /** The information field bytes. */
+  info: Uint8Array;
+  /** Mic-E only: the destination address, which carries half the position. */
+  destination?: string;
+}
+
+interface Attempt {
+  binary: string;
+  destination?: string;
+  compression?: CompressionType;
+}
+
+function withCompression(b: { text: string; compression?: CompressionType }): Attempt {
+  return b.compression ? { binary: b.text, compression: b.compression } : { binary: b.text };
+}
+
+function attempt(data: AprsData, mode: CommentMode): Attempt {
+  switch (data.type) {
+    case 'position':
+      return withCompression(encodePositionReport(data, mode));
+    case 'object':
+      return withCompression(encodeObject(data, mode));
+    case 'item':
+      return withCompression(encodeItem(data, mode));
+    case 'mic-e': {
+      const m = encodeMicE(data, mode);
+      return { binary: m.text, destination: m.destination };
+    }
+    case 'weather':
+      return { binary: encodeWeatherReport(data) };
+    case 'message':
+      return { binary: encodeMessage(data) };
+    case 'ack':
+    case 'reject':
+      return { binary: encodeAck(data) };
+    case 'bulletin':
+    case 'nws-bulletin':
+      return { binary: encodeBulletin(data) };
+    case 'telemetry-names':
+    case 'telemetry-units':
+      return { binary: encodeTelemetryNames(data) };
+    case 'telemetry-coefficients':
+      return { binary: encodeTelemetryCoefficients(data) };
+    case 'telemetry-bits':
+      return { binary: encodeTelemetryBits(data) };
+    case 'directed-query':
+      return { binary: encodeDirectedQuery(data) };
+    case 'status':
+      return { binary: encodeStatus(data) };
+    case 'telemetry':
+      return { binary: encodeTelemetryReport(data) };
+    case 'raw-weather':
+      return { binary: encodeRawWeather(data) };
+    case 'nmea':
+      return { binary: encodeNmea(data) };
+    case 'maidenhead-beacon':
+      return { binary: encodeMaidenhead(data) };
+    case 'query':
+      return { binary: encodeQuery(data) };
+    case 'capabilities':
+      return { binary: encodeCapabilities(data) };
+    case 'third-party': {
+      // The original information field must not be changed (APRS12c ch. 17).
+      const original = data.packet.information;
+      const inner = original.length > 0 ? original : encodeInformation(data.packet.data).info;
+      return { binary: encodeThirdParty(data, bytesToBinary(inner)) };
+    }
+    case 'user-defined':
+      return { binary: encodeUserDefined(data) };
+    case 'test':
+      return { binary: encodeTest(data) };
+    case 'agrelo-df':
+      return { binary: encodeAgrelo(data) };
+    case 'unrecognized':
+      return refuse('unrecognized data has nothing to encode');
+  }
+}
+
+/** Where the written data would read back differently: strings, booleans and which fields are present. */
+function shapeDifferences(a: unknown, b: unknown, path: string, out: string[]): void {
+  if (typeof a === 'number' && typeof b === 'number') return;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) out.push(`${path.replace(/\.$/, '')} would have ${a.length} items, not ${b.length}`);
+    else a.forEach((x, i) => shapeDifferences(x, b[i], `${path}${i}.`, out));
+    return;
+  }
+  if (a !== null && b !== null && typeof a === 'object' && typeof b === 'object') {
+    const ao = a as Record<string, unknown>;
+    const bo = b as Record<string, unknown>;
+    for (const k of new Set([...Object.keys(ao), ...Object.keys(bo)])) {
+      if (!(k in ao)) out.push(`${path}${k} would be lost`);
+      else if (!(k in bo)) out.push(`${path}${k} would appear`);
+      else shapeDifferences(ao[k], bo[k], `${path}${k}.`, out);
+    }
+    return;
+  }
+  if (a !== b) out.push(`${path.replace(/\.$/, '')} would read back as ${JSON.stringify(a)}`);
+}
+
+/** The data as it should read back: what the encoder fills in that the input may leave out. */
+function expected(data: AprsData, a: Attempt): AprsData {
+  let d = data;
+  if ((d.type === 'position' || d.type === 'object' || d.type === 'item') && d.compressed && a.compression) {
+    if (!d.compression) d = { ...d, compression: a.compression };
+    if (d.courseDegrees !== undefined && d.speedKnots === undefined) d = { ...d, speedKnots: 0 };
+  }
+  if (d.type === 'mic-e') {
+    if (d.speedKnots === undefined) d = { ...d, speedKnots: 0 };
+    if (d.courseDegrees === 0) {
+      const copy: Record<string, unknown> = { ...d };
+      delete copy.courseDegrees;
+      d = copy as unknown as AprsData;
+    }
+  }
+  return d;
+}
+
+function check(data: AprsData, a: Attempt): string[] {
+  const decoded = decodeInformation(binaryToBytes(a.binary), a.destination ?? 'APZ001', ParseOptions.lenient);
+  const problems: string[] = [];
+  const bad = decoded.diagnostics.filter((d) => d.severity !== 'info');
+  if (bad.length > 0) problems.push(`it would read back with ${bad.map(formatDiagnostic).join(', ')}`);
+  if (decoded.data.type !== data.type) {
+    problems.push(`it would read back as ${decoded.data.type}`);
+    return problems;
+  }
+  shapeDifferences(toNeutralData(decoded.data), toNeutralData(expected(data, a)), '', problems);
+  return problems;
+}
+
+/**
+ * Encodes data as an information field. Mic-E also gives the destination address it computed.
+ * Throws `AprsEncodeError`, with the reason, for anything the spec does not allow.
+ */
+export function encodeInformation(data: AprsData): EncodedInformation {
+  const first = attempt(data, 'plain');
+  let problems = check(data, first);
+  let chosen = first;
+  if (problems.length > 0 && typeof (data as { comment?: unknown }).comment === 'string') {
+    // The comment would read as something else: try it straight after a frequency, then after a /.
+    for (const mode of ['joined', 'delimited'] as const) {
+      let next: Attempt | undefined;
+      try {
+        next = attempt(data, mode);
+      } catch (e) {
+        if (!(e instanceof AprsEncodeError)) throw e;
+      }
+      if (next && next.binary !== first.binary && check(data, next).length === 0) {
+        chosen = next;
+        problems = [];
+        break;
+      }
+    }
+  }
+  if (problems.length > 0) refuse(`it would not read back the same: ${problems.join('; ')}`);
+  const out: EncodedInformation = { info: binaryToBytes(chosen.binary) };
+  if (chosen.destination !== undefined) out.destination = chosen.destination;
+  return out;
+}
+
+/** A packet to encode. */
+export interface PacketToEncode {
+  source: string;
+  /** The destination (tocall); ignored for Mic-E, which computes it. Defaults to `APZ001`. */
+  destination?: string;
+  /** Digipeater path, e.g. `['WIDE1-1', 'WIDE2-1']`; a trailing `*` marks an entry used. */
+  path?: readonly (string | PathEntry)[];
+  data: AprsData;
+}
+
+function pathText(entry: string | PathEntry): string {
+  return typeof entry === 'string' ? entry : entry.used ? `${entry.address}*` : entry.address;
+}
+
+function resolve(p: PacketToEncode): { destination: string; info: Uint8Array; path: string[] } {
+  const encoded = encodeInformation(p.data);
+  const destination = encoded.destination ?? p.destination ?? 'APZ001';
+  return { destination, info: encoded.info, path: (p.path ?? []).map(pathText) };
+}
+
+/** Encodes a packet as the bytes of a TNC2 / APRS-IS line (the information field as sent). */
+export function encodeTnc2Bytes(p: PacketToEncode): Uint8Array {
+  const r = resolve(p);
+  if (!isAprsIsAddress(p.source)) refuse(`the source ${JSON.stringify(p.source)} is not a valid address`);
+  if (!isAprsIsAddress(r.destination)) refuse(`the destination ${JSON.stringify(r.destination)} is not a valid address`);
+  for (const e of r.path) if (!isAprsIsAddress(e.replace(/\*$/, ''))) refuse(`the path entry ${JSON.stringify(e)} is not a valid address`);
+  const header = [`${p.source}>${r.destination}`, ...r.path].join(',') + ':';
+  const out = new Uint8Array(header.length + r.info.length);
+  out.set(binaryToBytes(header), 0);
+  out.set(r.info, header.length);
+  return out;
+}
+
+/**
+ * Encodes a packet as a TNC2 / APRS-IS line of text. User-defined data that is not UTF-8 has no
+ * text form; use `encodeTnc2Bytes` for that.
+ */
+export function encodeTnc2(p: PacketToEncode): string {
+  const text = decodeUtf8(encodeTnc2Bytes(p));
+  if (text === undefined) refuse('the information field is not UTF-8 text; use encodeTnc2Bytes');
+  return text;
+}
+
+function ax25Address(text: string, last: boolean, flag: boolean): number[] {
+  const m = /^([A-Z0-9]{1,6})(?:-([0-9]{1,2}))?$/.exec(text);
+  if (!m) refuse(`${JSON.stringify(text)} is not an AX.25 address`);
+  const ssid = m[2] === undefined ? 0 : Number(m[2]);
+  if (ssid > 15) refuse(`${JSON.stringify(text)} has an SSID over 15`);
+  const call = m[1]!.padEnd(6, ' ');
+  const out = Array.from(call, (c) => c.charCodeAt(0) << 1);
+  out.push(0x60 | (ssid << 1) | (flag ? 0x80 : 0) | (last ? 1 : 0));
+  return out;
+}
+
+/** Encodes a packet as an AX.25 UI frame in KISS form (no flags, no FCS). */
+export function encodeAx25(p: PacketToEncode): Uint8Array {
+  const r = resolve(p);
+  const path = p.path ?? [];
+  if (path.length > 8) refuse('AX.25 allows at most 8 digipeaters');
+  const bytes: number[] = [];
+  bytes.push(...ax25Address(r.destination, false, true));
+  bytes.push(...ax25Address(p.source, path.length === 0, false));
+  path.forEach((e, i) => {
+    const address = typeof e === 'string' ? e.replace(/\*$/, '') : e.address;
+    const used = typeof e === 'string' ? e.endsWith('*') : e.used;
+    bytes.push(...ax25Address(address, i === path.length - 1, used));
+  });
+  bytes.push(0x03, 0xf0, ...r.info);
+  return Uint8Array.from(bytes);
+}
+
+/** Wraps an AX.25 frame for a KISS TNC: FEND, a data command on `port`, escaping, FEND. */
+export function wrapKiss(frame: Uint8Array, port = 0): Uint8Array {
+  const out: number[] = [0xc0, (port & 0x0f) << 4];
+  for (const b of frame) {
+    if (b === 0xc0) out.push(0xdb, 0xdc);
+    else if (b === 0xdb) out.push(0xdb, 0xdd);
+    else out.push(b);
+  }
+  out.push(0xc0);
+  return Uint8Array.from(out);
+}