@packet-net/pdn-aprs 0.1.1 → 0.2.0

package/src/encode/other.ts

@@ -2,8 +2,9 @@
 // telemetry, queries, capabilities, and the rest.
 
 import { encodeUtf8Binary } from '../bytes.js';
-import { nmeaChecksumOk } from '../decode/other.js';
-import { formatPath } from '../header.js';
+import { DIRECTED_QUERY_TYPES } from '../decode/message.js';
+import { splitNmea } from '../decode/other.js';
+import { formatPath, isAprsIsAddress } from '../header.js';
 import type {
   Ack,
   AgreloDf,
@@ -124,7 +125,10 @@ export function encodeDirectedQuery(d: DirectedQuery): string {
   let out = `:${addressee(d.addressee)}:?${d.queryType}`;
   if (d.target !== undefined) {
     if (!/^[A-Za-z0-9-]{1,9}$/.test(d.target)) refuse('a query target is one callsign');
-    out += d.target;
+    // A type the spec defines is followed straight by the target, an APRSH target padded to 9
+    // characters; any other type has no fixed length, so its target follows one space.
+    if (!DIRECTED_QUERY_TYPES.includes(d.queryType)) out += ` ${d.target}`;
+    else out += d.queryType === 'APRSH' ? d.target.padEnd(9, ' ') : d.target;
   }
   return out;
 }
@@ -150,7 +154,7 @@ export function encodeStatus(d: StatusReport): string {
   }
   out += freeText(text, 'status text');
   if (d.beam) {
-    if (!/^[0-9A-Z]$/.test(d.beam.headingCode) || !/^[0-9:;<=>?@A-K]$/.test(d.beam.powerCode))
+    if (!/^[0-9A-Z]$/.test(d.beam.headingCode) || !/^[1-9:;<=>?@A-K]$/.test(d.beam.powerCode))
       refuse('beam heading is 0-9 or A-Z, and power 1-9 or :-K');
     out += `^${d.beam.headingCode}${d.beam.powerCode}`;
   }
@@ -186,10 +190,12 @@ export function encodeRawWeather(d: RawWeather): string {
 }
 
 export function encodeNmea(d: NmeaSentence): string {
-  if (!/^[A-Z]{5},[\x20-\x7e]*$/.test(d.sentence)) refuse('not an NMEA sentence');
-  const checksum = nmeaChecksumOk(d.sentence);
-  if (checksum === false) refuse("the NMEA sentence's checksum does not match");
-  return `$${d.sentence}`;
+  const parts = splitNmea(d.sentence);
+  if (!parts || parts.rest.length > 0) refuse('not an NMEA 0183 sentence');
+  if (!parts.checksumOk) refuse("the NMEA sentence's checksum does not match");
+  const comment = d.comment ?? '';
+  if (comment.length > 0 && !parts.hasChecksum) refuse('a comment after an NMEA sentence needs the checksum that ends the sentence');
+  return `$${d.sentence}${freeText(comment, 'the comment')}`;
 }
 
 export function encodeMaidenhead(d: MaidenheadBeacon): string {
@@ -209,14 +215,20 @@ export function encodeQuery(d: Query): string {
   return out;
 }
 
+/** A control character: below U+0020, or U+007F. */
+const CONTROL_RE = /[\x00-\x1f\x7f]/;
+
 export function encodeCapabilities(d: Capabilities): string {
   if (d.capabilities.length === 0) refuse('capabilities need at least one item');
+  // Anything that would not read back the same (vectors interpretations.md, "Station
+  // capabilities: items, tokens and values") is refused.
   const items = d.capabilities.map((c) => {
     const token = c[0];
-    if (token.length === 0 || /[\s,=]/.test(token)) refuse('a capability token has no space, comma or =');
+    if (token.length === 0 || /[ ,=]/.test(token) || CONTROL_RE.test(token)) refuse('a capability token is not empty and has no space, control character, comma or =');
     if (c.length === 1) return token;
     const value = c[1]!;
-    if (value.includes(',') || /^\s|\s$/.test(value)) refuse('a capability value has no comma or edge spaces');
+    if (value.includes(',') || CONTROL_RE.test(value) || value.startsWith(' ') || value.endsWith(' '))
+      refuse('a capability value has no comma or control character, and does not start or end with a space');
     return `${token}=${value}`;
   });
   return '<' + encodeUtf8Binary(items.join(','));
@@ -241,7 +253,11 @@ export function encodeAgrelo(d: AgreloDf): string {
 /** The third-party header and the encapsulated packet's information field. */
 export function encodeThirdParty(d: ThirdParty, innerInfo: string): string {
   const p = d.packet;
+  // The source is 1-9 printable ASCII characters other than > and : (APRS12c ch. 17); the
+  // destination and path are APRS-IS addresses.
+  if (!/^[\x20-\x39\x3b-\x3d\x3f-\x7e]{1,9}$/.test(p.source)) refuse('a third-party source is 1-9 printable ASCII characters other than > and :');
+  if (!isAprsIsAddress(p.destination)) refuse('the third-party destination is not a valid address');
+  for (const e of p.path) if (!isAprsIsAddress(e.address)) refuse(`the third-party path entry ${JSON.stringify(e.address)} is not a valid address`);
   const header = p.path.length > 0 ? `${p.source}>${p.destination},${formatPath(p.path)}` : `${p.source}>${p.destination}`;
-  if (!/^[\x21-\x7e]+$/.test(header) || header.includes(':')) refuse('the third-party header is not printable');
   return `}${header}:${innerInfo}`;
 }

package/src/encode/position.ts

@@ -109,6 +109,18 @@ function compressedPosition(f: PositionedFields, cs: string | undefined, compres
   return table + base91(y, 4) + base91(x, 4) + f.symbol.code + tail;
 }
 
+/**
+ * A GGA altitude in the cs bytes: 1.002^cs feet, so the nearest value they hold (1 foot for 0 feet
+ * or below), and whether that is exact. When it is not, a `/A=` altitude carries it and wins.
+ */
+function ggaAltitude(feet: number): { cs: string; exact: boolean } {
+  if (!Number.isFinite(feet)) refuse('altitude is not a number');
+  const v = feet <= 1 ? 0 : Math.round(Math.log(feet) / Math.log(1.002));
+  if (v > 91 * 91 - 1) refuse('altitude is too high for the compressed format');
+  const cs = String.fromCharCode(Math.floor(v / 91) + 33) + String.fromCharCode((v % 91) + 33);
+  return { cs, exact: Math.abs(Math.pow(1.002, v) - feet) <= 1e-9 * Math.abs(feet) };
+}
+
 // ---- data extensions and comment elements
 
 function courseSpeed(course: number | undefined, speed: number | undefined, what = 'course'): string {
@@ -191,14 +203,20 @@ export function telemetryText(t: CommentTelemetry): string {
   const v = (n: number, what: string): string => base91(whole(n, 0, 8280, what), 2);
   let out = '|' + v(t.sequence, 'telemetry sequence');
   for (const a of t.analog) out += v(a, 'telemetry value');
-  if (t.digital !== undefined) out += v(t.digital, 'telemetry bits');
+  // Eight binary channels; bits 9-13 are reserved.
+  if (t.digital !== undefined) out += base91(whole(t.digital, 0, 255, 'telemetry bits'), 2);
   return out + '|';
 }
 
 function daoText(f: PositionedFields, latRemainder: number, lonRemainder: number, applied: boolean): string {
   const dao = f.dao!;
   const datum = dao.datum;
-  if (!/^[A-Za-z]$/.test(datum)) refuse('the !DAO! datum is a letter');
+  if (/^[0-9]$/.test(datum)) {
+    // A local datum digit has no case to give a precision, so it only goes with spaces.
+    if (dao.precision !== 'none') refuse('a !DAO! datum digit carries no added precision');
+    return `!${datum}  !`;
+  }
+  if (!/^[A-Za-z]$/.test(datum)) refuse('the !DAO! datum is a letter or a digit');
   switch (dao.precision) {
     case 'none':
       return `!${datum.toUpperCase()}  !`;
@@ -226,6 +244,22 @@ function weatherValue(v: number | undefined, width: number, min: number, max: nu
   return pad(n, width);
 }
 
+/**
+ * Snowfall written exactly in its three characters, with a decimal point where it needs one
+ * (0.32 as `.32`), and refused when they cannot hold it.
+ */
+function snowfallText(inches: number): string {
+  if (!Number.isFinite(inches) || inches < 0) refuse('snowfall is not a number of inches');
+  let text: string;
+  if (Number.isInteger(inches)) text = pad(whole(inches, 0, 999, 'snowfall'), 3);
+  else if (String(inches).length === 3) text = String(inches);
+  else text = inches < 1 ? '.' + pad(Math.round(inches * 100), 2) : '';
+  if (!/^[0-9.]{3}$/.test(text) || /\..*\./.test(text) || Math.abs(Number(text) - inches) > 1e-9) {
+    refuse(`snowfall ${inches} does not fit in 3 characters`);
+  }
+  return text;
+}
+
 /** Weather fields after the wind: gust, temperature, rain, humidity, pressure, and on. */
 function weatherFields(w: Weather, mandatory: boolean): string {
   let out = '';
@@ -243,12 +277,7 @@ function weatherFields(w: Weather, mandatory: boolean): string {
     const l = whole(w.luminosityWM2, 0, 1999, 'luminosity');
     out += l < 1000 ? 'L' + pad(l, 3) : 'l' + pad(l - 1000, 3);
   }
-  if (w.snow24hIn !== undefined) {
-    const s = w.snow24hIn;
-    let text = Number.isInteger(s) ? pad(whole(s, 0, 999, 'snowfall'), 3) : String(s);
-    if (text.length !== 3 || !/^[0-9.]{3}$/.test(text)) text = refuse('snowfall is 3 characters');
-    out += 's' + text;
-  }
+  if (w.snow24hIn !== undefined) out += 's' + snowfallText(w.snow24hIn);
   if (w.rainRaw !== undefined) out += '#' + pad(whole(w.rainRaw, 0, 999, 'raw rain counter'), 3);
   for (const e of w.extra ?? []) {
     if (!/^[A-Za-z]$/.test(e.letter) || 'csgtrpPhbLl'.includes(e.letter)) refuse(`${e.letter} is not an extra weather field letter`);
@@ -296,9 +325,11 @@ function hasExtension(f: PositionedFields): string[] {
 /**
  * How the comment is joined on: `plain` (after a space when it follows a frequency), `joined`
  * (straight after a frequency, with no space) or `delimited` (after a `/`), for when it would
- * otherwise read as something else.
+ * otherwise read as something else; or `braces-first`, as `plain` but with the signpost or
+ * corridor braces written before the comment, for a comment holding braces that would be taken
+ * for them (the first well-formed braces are the signpost).
  */
-export type CommentMode = 'plain' | 'joined' | 'delimited';
+export type CommentMode = 'plain' | 'joined' | 'delimited' | 'braces-first';
 
 /** Encodes a position and what follows it. */
 function positionedBody(f: PositionedFields, mode: CommentMode): Body {
@@ -342,11 +373,9 @@ function positionedBody(f: PositionedFields, mode: CommentMode): Body {
       cs = '{' + String.fromCharCode(s + 33);
       compression = compression ?? DEFAULT_COMPRESSION;
     } else if (f.altitudeFeet !== undefined && compression?.source === 'gga') {
-      if (f.altitudeFeet < 1) refuse('a compressed altitude is at least 1 foot');
-      const v = Math.round(Math.log(f.altitudeFeet) / Math.log(1.002));
-      if (v > 91 * 91 - 1) refuse('altitude is too high for the compressed format');
-      cs = String.fromCharCode(Math.floor(v / 91) + 33) + String.fromCharCode((v % 91) + 33);
-      altitudeInCs = Math.abs(Math.pow(1.002, v) - f.altitudeFeet) <= 1e-9 * f.altitudeFeet;
+      const alt = ggaAltitude(f.altitudeFeet);
+      cs = alt.cs;
+      altitudeInCs = alt.exact;
     } else if (compression !== undefined) {
       refuse('a compression type needs cs data (course/speed, range or altitude)');
     }
@@ -393,7 +422,8 @@ function positionedBody(f: PositionedFields, mode: CommentMode): Body {
   if (f.frequency) text += (extensionEnded && !out.endsWith('/') ? '/' : '') + frequencyText(f.frequency);
   let braces = '';
   if (f.signpost !== undefined) {
-    if (!/^[\x21-\x7c\x7e]{1,3}$/.test(f.signpost) || f.signpost.includes('{') || f.signpost.includes('}')) refuse('a signpost is 1-3 printable characters');
+    // Printable ASCII, a space included, other than the braces around it.
+    if (!/^[\x20-\x7a\x7c\x7e]{1,3}$/.test(f.signpost)) refuse('a signpost is 1-3 printable ASCII characters other than { and }');
     braces = `{${f.signpost}}`;
   }
   if (f.area?.corridorWidthMiles !== undefined) {
@@ -405,7 +435,7 @@ function positionedBody(f: PositionedFields, mode: CommentMode): Body {
     if (text.length > 0 && mode !== 'joined') text += ' ';
     text += (mode === 'delimited' ? '/' : '') + freeText(comment, 'the comment');
   }
-  text += braces;
+  text = mode === 'braces-first' ? braces + text : text + braces;
   if (f.telemetry) text += telemetryText(f.telemetry);
   if (f.dao) text += daoText(f, latRem, lonRem, daoApplied);
   const body: Body = { text: out + text };
@@ -448,9 +478,9 @@ function weatherBody(f: PositionedFields): Body {
       compression = compression ?? DEFAULT_COMPRESSION;
       if (compression.source === 'gga') refuse('a GGA compression type means the cs bytes hold altitude');
     } else if (f.altitudeFeet !== undefined && compression?.source === 'gga') {
-      const v = Math.round(Math.log(f.altitudeFeet) / Math.log(1.002));
-      cs = String.fromCharCode(Math.floor(v / 91) + 33) + String.fromCharCode((v % 91) + 33);
-      altitudeInCs = Math.abs(Math.pow(1.002, v) - f.altitudeFeet) <= 1e-9 * f.altitudeFeet;
+      const alt = ggaAltitude(f.altitudeFeet);
+      cs = alt.cs;
+      altitudeInCs = alt.exact;
     } else if (f.rangeMiles !== undefined) {
       if (compression?.source === 'gga') refuse('a GGA compression type means the cs bytes hold altitude');
       const s = Math.round(Math.log(f.rangeMiles / 2) / Math.log(1.08));
@@ -656,6 +686,10 @@ export function encodeMicE(d: MicEReport, mode: CommentMode): { text: string; de
     if (d.typeCode === undefined) refuse('a Mic-E device suffix needs a type code');
     text += d.deviceSuffix;
   }
+  // Mic-E status text must not start with 0x1D, which would be taken for Rev 0 telemetry
+  // (APRS12c ch. 10), so a comment that would start it is written after a /.
+  const legacy = d.legacyTelemetry !== undefined && d.legacyTelemetry.length > 0;
+  if (!legacy && text.startsWith('\x1d') && mode !== 'delimited') return encodeMicE(d, 'delimited');
   info += text;
   return { text: info, destination };
 }

package/src/header.ts

@@ -71,17 +71,24 @@ export function parseTnc2Header(line: Uint8Array, options: ParseOptions): Parsed
   }
 }
 
-/** Parses `SOURCE>DEST,PATH` (without the colon). Used for TNC2 lines and third-party headers. */
+/** A third-party source: 1-9 printable ASCII characters (APRS12c ch. 17); `>` and `:` end it. */
+const THIRD_PARTY_SOURCE = /^[\x20-\x7e]{1,9}$/;
+
+/**
+ * Parses `SOURCE>DEST,PATH` (without the colon). Used for TNC2 lines and third-party headers,
+ * whose source need not be an APRS-IS address (`thirdParty`).
+ */
 export function parseHeaderText(
   header: string,
   options: ParseOptions,
   diags: Diagnostic[],
+  thirdParty = false,
 ): { source: string; destination: string; path: PathEntry[] } {
   const gt = header.indexOf('>');
   if (gt < 0) fail(diags, 'invalid-header');
   const source = header.slice(0, gt);
   if (source.length === 0) fail(diags, 'invalid-header');
-  if (!APRS_IS_ADDRESS.test(source)) fail(diags, 'invalid-address');
+  if (!(thirdParty ? THIRD_PARTY_SOURCE : APRS_IS_ADDRESS).test(source)) fail(diags, 'invalid-address');
   const parts = header.slice(gt + 1).split(',');
   const destination = parts[0]!;
   if (destination.length === 0) tolerate(options, diags, 'empty-destination');

package/src/neutral.ts

@@ -281,6 +281,7 @@ export function toNeutralData(d: AprsData): Neutral {
       put(o, 'altitude_m', d.altitudeM);
       put(o, 'time', d.time);
       put(o, 'waypoint', d.waypoint);
+      put(o, 'comment', d.comment);
       break;
     case 'maidenhead-beacon':
       put(o, 'locator', d.locator);
@@ -560,6 +561,7 @@ export function fromNeutralData(d: J): AprsData {
       opt(o, 'altitudeM', d.altitude_m);
       opt(o, 'time', d.time);
       opt(o, 'waypoint', d.waypoint);
+      opt(o, 'comment', d.comment);
       break;
     case 'maidenhead-beacon':
       o.locator = d.locator ?? '';

package/src/types.ts

@@ -136,7 +136,7 @@ export type DaoPrecision = 'none' | 'thousandths' | 'base91';
 
 /** The `!DAO!` datum and precision (APRS12c ch. 5). */
 export interface Dao {
-  /** The datum letter, upper case (`W` is WGS84). */
+  /** The datum: a letter, upper case (`W` is WGS84), or a digit for a local datum. */
   readonly datum: string;
   readonly precision: DaoPrecision;
 }
@@ -146,7 +146,7 @@ export interface CommentTelemetry {
   readonly sequence: number;
   /** One to five analog values, 0-8280. */
   readonly analog: readonly number[];
-  /** The eight digital bits as a number, B1 the least significant bit. */
+  /** The eight binary channels as a number, 0-255, B1 the least significant bit. */
   readonly digital?: number;
 }
 
@@ -419,7 +419,7 @@ export interface RawWeather {
 /** A raw NMEA sentence (`$`). */
 export interface NmeaSentence {
   readonly type: 'nmea';
-  /** The sentence without the `$`. */
+  /** The sentence without the `$`, up to and including any `*hh` checksum. */
   readonly sentence: string;
   readonly hasChecksum?: boolean;
   readonly latitude?: number;
@@ -428,9 +428,11 @@ export interface NmeaSentence {
   readonly courseDegrees?: number;
   readonly speedKnots?: number;
   readonly altitudeM?: number;
-  /** `HH:MM:SS`, with any fraction of a second. */
+  /** `HH:MM:SS`, with any fraction of a second as sent. */
   readonly time?: string;
   readonly waypoint?: string;
+  /** Text after the checksum (TinyTrack and FreeTrak send one), as sent. */
+  readonly comment?: string;
 }
 
 /** A Maidenhead locator beacon (`[`), obsolete. */