node-red-contrib-ax25 1.0.0

package/lib/agwpe-client-transport.js

@@ -0,0 +1,99 @@
+"use strict";
+
+const net = require("net");
+const EventEmitter = require("events");
+const { prettyPrintAgwpeFrame } = require("./agwpe-frame-pretty");
+
+class AgwpeClientTransport extends EventEmitter {
+  constructor(options) {
+    super();
+    const opts = options || {};
+    this.socketFactory = opts.socketFactory || net.createConnection;
+    this.logger = opts.logger || function () {};
+    this.socket = null;
+    this.state = "disconnected";
+  }
+
+  open(host, port, callback) {
+    const done = typeof callback === "function" ? callback : function () {};
+    if (this.state === "connecting" || this.state === "connected") {
+      done(new Error("TRANSPORT_ALREADY_OPEN"));
+      return;
+    }
+
+    this.state = "connecting";
+    this.logger(`AGWPE transport connecting to ${host}:${port}`);
+    const socket = this.socketFactory({ host, port });
+    socket.setKeepAlive(true, 10000);
+    this.socket = socket;
+
+    socket.on("connect", () => {
+      this.state = "connected";
+      this.logger(`AGWPE transport connected to ${host}:${port}`);
+      this.emit("connected");
+      done(null);
+    });
+
+    socket.on("data", (data) => {
+      this.logger(prettyPrintAgwpeFrame(data, { direction: "rx" }));
+      this.emit("frame", data);
+    });
+
+    socket.on("error", (error) => {
+      this.state = "failed";
+      this.logger(`AGWPE transport error: ${error.message}`);
+      this.emit("error", error);
+    });
+
+    socket.on("close", () => {
+      this.state = "disconnected";
+      this.logger(`AGWPE transport closed`);
+      this.emit("closed");
+    });
+  }
+
+  sendFrame(frame, callback) {
+    const done = typeof callback === "function" ? callback : function () {};
+    if (!this.socket || this.state !== "connected") {
+      done(new Error("TRANSPORT_NOT_CONNECTED"));
+      return;
+    }
+    this.logger(prettyPrintAgwpeFrame(frame, { direction: "tx" }));
+    this.socket.write(frame, done);
+  }
+
+  close(callback) {
+    const done = typeof callback === "function" ? callback : function () {};
+    if (!this.socket) {
+      this.state = "disconnected";
+      done(null);
+      return;
+    }
+
+    const socket = this.socket;
+    this.socket = null;
+    this.state = "closing";
+    this.logger(`AGWPE transport closing`);
+
+    if (socket.destroyed) {
+      this.state = "disconnected";
+      this.logger(`AGWPE transport closed`);
+      done(null);
+      return;
+    }
+
+    let settled = false;
+    const settle = () => {
+      if (settled) return;
+      settled = true;
+      this.state = "disconnected";
+      this.logger(`AGWPE transport closed`);
+      done(null);
+    };
+
+    socket.once("close", settle);
+    socket.end(settle);
+  }
+}
+
+module.exports = AgwpeClientTransport;

package/lib/agwpe-frame-builder.js

@@ -0,0 +1,176 @@
+"use strict";
+
+/**
+ * AGWPE wire frame builder.
+ *
+ * All AGWPE frames share a 36-byte header:
+ *   byte 0:     Port (0-based)
+ *   bytes 1-3:  reserved
+ *   byte 4:     DataKind (ASCII: 'X'=register, 'C'=connect, 'd'=disconnect, 'D'=data, 'M'=UI)
+ *   byte 5:     reserved
+ *   byte 6:     PID (typically 0xF0 for AX.25 UI/I payloads)
+ *   byte 7:     reserved
+ *   bytes 8-17: CallSign From (10 bytes, null-padded, uppercase ASCII)
+ *   bytes 18-27:CallSign To   (10 bytes, null-padded, uppercase ASCII)
+ *   bytes 28-31:DataLength    (uint32 LE) — length of data following header
+ *   bytes 32-35:User/reserved (uint32 LE)
+ *
+ * Data payload (if any) follows immediately after the 36-byte header.
+ */
+
+const HEADER_LEN = 36;
+
+function encodeCallsign(callsign) {
+  const out = Buffer.alloc(10);
+  const normalized = String(callsign || "")
+    .trim()
+    .toUpperCase()
+    .slice(0, 9);
+  Buffer.from(normalized, "ascii").copy(out, 0);
+  return out;
+}
+
+/**
+ * Build an AGWPE frame.
+ *
+ * @param {object} opts
+ * @param {string} opts.kind       - DataKind character (e.g. 'C', 'D', 'd', 'M')
+ * @param {string} [opts.from]     - Source callsign
+ * @param {string} [opts.to]       - Destination callsign
+ * @param {Buffer} [opts.payload]  - Data payload (appended after header)
+ * @param {number} [opts.port]     - Port number (default 0)
+ * @param {number} [opts.pid]      - AX.25 PID byte (default 0)
+ * @param {number} [opts.user]     - User reserved field (default 0)
+ * @returns {Buffer}
+ */
+function buildAgwpeFrame(opts) {
+  const kind = String(opts.kind || "").charCodeAt(0);
+  const payload = Buffer.isBuffer(opts.payload) ? opts.payload : Buffer.alloc(0);
+  const frame = Buffer.alloc(HEADER_LEN + payload.length);
+
+  frame.writeUInt8(opts.port || 0, 0);
+  frame.writeUInt8(kind, 4);
+  frame.writeUInt8(opts.pid || 0, 6);
+  encodeCallsign(opts.from).copy(frame, 8);
+  encodeCallsign(opts.to).copy(frame, 18);
+  frame.writeUInt32LE(payload.length, 28);
+  frame.writeUInt32LE(opts.user || 0, 32);
+
+  if (payload.length > 0) {
+    payload.copy(frame, HEADER_LEN);
+  }
+
+  return frame;
+}
+
+/**
+ * Build a 'C' (connect) frame.
+ */
+function makeConnectFrame(source, destination) {
+  return buildAgwpeFrame({ kind: "C", from: source, to: destination });
+}
+
+/**
+ * Build a 'v' (connect via digipeaters) frame.
+ *
+ * The payload contains the digipeater callsigns, each encoded as 10 bytes
+ * (null-padded uppercase ASCII), matching the AGWPE callsign field format.
+ * DataLen = N * 10 where N is the number of via stations.
+ *
+ * @param {string}          source       - Our callsign.
+ * @param {string}          destination  - Remote callsign.
+ * @param {string[]|object[]} viaCallsigns - Digipeater callsigns (strings or
+ *   objects with a .callsign property).
+ * @returns {Buffer}
+ */
+function makeViaConnectFrame(source, destination, viaCallsigns) {
+  const via = Array.isArray(viaCallsigns) ? viaCallsigns : [];
+  const viaCount = Buffer.from([via.length & 0xff]);
+  const viaBuffers = via.map(function (cs) {
+    return encodeCallsign(typeof cs === "object" ? cs.callsign : cs);
+  });
+  const viaPayload = Buffer.concat([viaCount].concat(viaBuffers));
+  return buildAgwpeFrame({ kind: "v", from: source, to: destination, payload: viaPayload });
+}
+
+/**
+ * Build an 'X' (register callsign) frame.
+ */
+function makeRegistrationFrame(callsign) {
+  return buildAgwpeFrame({ kind: "X", from: callsign });
+}
+
+/**
+ * Build a 'd' (disconnect) frame.
+ */
+function makeDisconnectFrame(source, destination) {
+  return buildAgwpeFrame({ kind: "d", from: source, to: destination });
+}
+
+/**
+ * Build a 'D' (connected data) frame.
+ */
+function makeDataFrame(source, destination, payload) {
+  const data = Buffer.isBuffer(payload)
+    ? payload
+    : Buffer.from(payload || "", "utf8");
+  return buildAgwpeFrame({ kind: "D", from: source, to: destination, pid: 0xf0, payload: data });
+}
+
+/**
+ * Build an 'M' (UI / unconnected) frame.
+ */
+function makeUiFrame(source, destination, payload) {
+  const data = Buffer.isBuffer(payload)
+    ? payload
+    : Buffer.from(payload || "", "utf8");
+  return buildAgwpeFrame({ kind: "M", from: source, to: destination, pid: 0xf0, payload: data });
+}
+
+/**
+ * Build a 'K' (raw AX.25) frame.
+ */
+function makeRawFrame(source, destination, payload) {
+  const data = Buffer.isBuffer(payload)
+    ? payload
+    : Buffer.from(payload || "", "utf8");
+  return buildAgwpeFrame({ kind: "K", from: source, to: destination, payload: data });
+}
+
+/**
+ * Build a 'y' (query outstanding frames) frame.
+ * Asks the TNC how many unacknowledged I-frames are still pending for a
+ * specific connected callsign pair.  The TNC replies with a 'Y' frame
+ * whose DataLen field contains the outstanding count.
+ */
+function makeOutstandingQueryFrame(source, destination) {
+  return buildAgwpeFrame({ kind: "y", from: source, to: destination });
+}
+
+/**
+ * Build an 'm' command frame to toggle monitor traffic streaming.
+ */
+function makeMonitorToggleFrame() {
+  return buildAgwpeFrame({ kind: "m" });
+}
+
+/**
+ * Build a 'k' command frame to toggle raw frame streaming.
+ */
+function makeRawToggleFrame() {
+  return buildAgwpeFrame({ kind: "k" });
+}
+
+module.exports = {
+  buildAgwpeFrame,
+  makeRegistrationFrame,
+  makeConnectFrame,
+  makeViaConnectFrame,
+  makeDisconnectFrame,
+  makeDataFrame,
+  makeUiFrame,
+  makeRawFrame,
+  makeMonitorToggleFrame,
+  makeRawToggleFrame,
+  makeOutstandingQueryFrame
+};

package/lib/agwpe-frame-pretty.js

@@ -0,0 +1,107 @@
+"use strict";
+
+const AGWPE_HEADER_LEN = 36;
+
+function toHexPreview(buffer, maxBytes) {
+  const limit = Number.isInteger(maxBytes) && maxBytes > 0 ? maxBytes : 32;
+  const view = buffer.subarray(0, limit);
+  const hex = view.toString("hex");
+  return hex.match(/.{1,2}/g)?.join(" ") || "";
+}
+
+function toAsciiPreview(buffer, maxBytes) {
+  const limit = Number.isInteger(maxBytes) && maxBytes > 0 ? maxBytes : 32;
+  const view = buffer.subarray(0, limit);
+  return view
+    .toString("utf8")
+    .replace(/[\x00-\x1F\x7F]/g, ".");
+}
+
+function decodeCallsign(buffer, offset) {
+  const raw = buffer.subarray(offset, offset + 10);
+  const nul = raw.indexOf(0x00);
+  const end = nul >= 0 ? nul : raw.length;
+  return raw.subarray(0, end).toString("ascii").trim();
+}
+
+function toDataKindChar(byteValue) {
+  if (byteValue >= 32 && byteValue <= 126) {
+    return String.fromCharCode(byteValue);
+  }
+  return "?";
+}
+
+function prettyPrintAgwpeFrame(frame, options) {
+  const opts = options || {};
+  const direction = opts.direction ? String(opts.direction) : "?";
+
+  if (Buffer.isBuffer(frame)) {
+    const parts = [
+      `AGWPE frame ${direction} buffer`,
+      `len=${frame.length}`
+    ];
+
+    if (frame.length >= AGWPE_HEADER_LEN) {
+      const dataKindByte = frame.readUInt8(4);
+      const dataLen = frame.readUInt32LE(28);
+      const payloadAvailable = Math.max(0, frame.length - AGWPE_HEADER_LEN);
+      const payloadExtractLen = Math.min(dataLen, payloadAvailable);
+      const payload = frame.subarray(AGWPE_HEADER_LEN, AGWPE_HEADER_LEN + payloadExtractLen);
+
+      parts.push(`port=${frame.readUInt8(0)}`);
+      parts.push(`dataKind=${toDataKindChar(dataKindByte)}(0x${dataKindByte.toString(16).padStart(2, "0")})`);
+      parts.push(`pid=0x${frame.readUInt8(6).toString(16).padStart(2, "0")}`);
+      parts.push(`from=${decodeCallsign(frame, 8) || "-"}`);
+      parts.push(`to=${decodeCallsign(frame, 18) || "-"}`);
+      parts.push(`dataLen=${dataLen}`);
+      parts.push(`user=${frame.readUInt32LE(32)}`);
+      parts.push(`payloadAvailable=${payloadAvailable}`);
+      parts.push(`complete=${payloadAvailable >= dataLen}`);
+
+      if (payloadExtractLen > 0) {
+        parts.push(`payloadHex=${toHexPreview(payload, opts.maxPreviewBytes)}`);
+        parts.push(`payloadAscii=${toAsciiPreview(payload, opts.maxPreviewBytes)}`);
+      }
+    } else {
+      parts.push(`hex=${toHexPreview(frame, opts.maxPreviewBytes)}`);
+      parts.push(`ascii=${toAsciiPreview(frame, opts.maxPreviewBytes)}`);
+    }
+
+    return parts.join(" | ");
+  }
+
+  if (!frame || typeof frame !== "object") {
+    return `AGWPE frame ${direction} invalid=${String(frame)}`;
+  }
+
+  const parts = [
+    `AGWPE frame ${direction}`,
+    `kind=${frame.kind || "unknown"}`
+  ];
+
+  if (frame.sessionId !== undefined) {
+    parts.push(`sessionId=${frame.sessionId}`);
+  }
+  if (frame.source) {
+    parts.push(`source=${frame.source}`);
+  }
+  if (frame.destination) {
+    parts.push(`destination=${frame.destination}`);
+  }
+  if (frame.event) {
+    parts.push(`event=${frame.event}`);
+  }
+
+  if (Buffer.isBuffer(frame.payload)) {
+    parts.push(`payloadLen=${frame.payload.length}`);
+    parts.push(`payloadHex=${toHexPreview(frame.payload, opts.maxPreviewBytes)}`);
+  } else if (typeof frame.payload === "string") {
+    parts.push(`payload="${frame.payload.slice(0, 64)}${frame.payload.length > 64 ? "..." : ""}"`);
+  }
+
+  return parts.join(" | ");
+}
+
+module.exports = {
+  prettyPrintAgwpeFrame
+};