node-red-contrib-ax25 1.0.0

package/nodes/decode.js

@@ -0,0 +1,56 @@
+"use strict";
+
+const codec = require("../lib/ax25-codec");
+const { okEnvelope, errorEnvelope } = require("../lib/message-utils");
+
+module.exports = function (RED) {
+  function DecodeNode(config) {
+    RED.nodes.createNode(this, config);
+    const node = this;
+    node.payloadOutput = config.payloadOutput === "buffer" ? "buffer" : "string";
+
+    function normalizeAgwpePort(value) {
+      if (Buffer.isBuffer(value)) {
+        return value.length > 0 ? value.readUInt8(0) : 0;
+      }
+      const numeric = Number(value);
+      if (Number.isInteger(numeric) && numeric >= 0 && numeric <= 255) {
+        return numeric;
+      }
+      return 0;
+    }
+
+    node.on("input", function (msg, send, done) {
+      const localSend = send || function (m) {
+        node.send(m);
+      };
+      const localDone = done || function () {};
+
+      if (!Buffer.isBuffer(msg.payload)) {
+        localSend(errorEnvelope("DECODE_INPUT_INVALID", "payload must be Buffer"));
+        localDone();
+        return;
+      }
+
+      try {
+        const parsed = codec.decode(msg.payload);
+        const rawPort = msg.agwpePort !== undefined
+          ? msg.agwpePort
+          : (msg.agwpePrefix !== undefined ? msg.agwpePrefix : 0);
+        const out = Object.assign(
+          { agwpePort: normalizeAgwpePort(rawPort) },
+          parsed
+        );
+        if (node.payloadOutput === "string" && Buffer.isBuffer(out.payload)) {
+          out.payload = out.payload.toString("utf8");
+        }
+        localSend(okEnvelope(out));
+      } catch (error) {
+        localSend(errorEnvelope("DECODE_FAILED", error.message));
+      }
+      localDone();
+    });
+  }
+
+  RED.nodes.registerType("decode", DecodeNode);
+};

package/nodes/disconnect.html

@@ -0,0 +1,55 @@
+<script type="text/javascript">
+RED.nodes.registerType("disconnect", {
+  category: "agwpe",
+  color: "#d4edda",
+  defaults: {
+    name: { value: "" }
+  },
+  inputs: 1,
+  outputs: 1,
+  outputLabels: ["events"],
+  icon: "font-awesome/fa-sign-out",
+  label: function () {
+    return this.name || "disconnect";
+  }
+});
+</script>
+
+<script type="text/html" data-template-name="disconnect">
+  <div class="form-row">
+    <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+    <input type="text" id="node-input-name" />
+  </div>
+</script>
+
+<script type="text/html" data-help-name="disconnect">
+  <p>Initiates a graceful disconnect for an AX.25 connected session.</p>
+
+  <h3>Input</h3>
+  <dl class="message-properties">
+    <dt>sessionId <span class="property-type">string</span></dt>
+    <dd>Session to disconnect.</dd>
+  </dl>
+
+  <h3>Outputs</h3>
+  <ol class="node-ports">
+    <li>Events
+      <dl class="message-properties">
+        <dt>status <span class="property-type">string</span></dt>
+        <dd><code>"ok"</code> on success; <code>"error"</code> on error.</dd>
+        <dt>event <span class="property-type">string</span></dt>
+        <dd>When <code>status</code> is <code>"ok"</code>: <code>disconnecting</code>.</dd>
+        <dt>sessionId <span class="property-type">string</span></dt>
+        <dd>Identifies the session.</dd>
+        <dt class="optional">errorCode <span class="property-type">string</span></dt>
+        <dd>When <code>status</code> is <code>"error"</code>: <code>SESSION_NOT_FOUND</code>.</dd>
+        <dt class="optional">errorText <span class="property-type">string</span></dt>
+        <dd>When <code>status</code> is <code>"error"</code>: human-readable description of the error.</dd>
+      </dl>
+    </li>
+  </ol>
+
+  <h3>Details</h3>
+  <p>Emits <code>disconnecting</code> immediately. The <code>disconnected</code> event fires on the
+  originating <b>Connect</b> node's event output once the TNC confirms with a <code>d</code> frame.</p>
+</script>

package/nodes/disconnect.js

@@ -0,0 +1,47 @@
+"use strict";
+
+const { okEnvelope, errorEnvelope } = require("../lib/message-utils");
+const store = require("../lib/runtime-store");
+
+module.exports = function (RED) {
+  function DisconnectNode(config) {
+    RED.nodes.createNode(this, config);
+    const node = this;
+
+    node.status({});
+
+    node.on("input", function (msg, send, done) {
+      const localSend = send || function (m) { node.send(m); };
+      const localDone = done || function () {};
+
+      const iid = store.instanceIdForSession(msg.sessionId);
+      const ctx = iid ? store.getInstance(iid) : null;
+      const session = ctx ? ctx.registry.get(ctx.instanceId, msg.sessionId) : null;
+      if (!session) {
+        localSend(errorEnvelope("SESSION_NOT_FOUND", "Session not found", { sessionId: msg.sessionId }));
+        localDone();
+        return;
+      }
+
+      ctx.registry.update(ctx.instanceId, msg.sessionId, { state: "disconnecting" });
+      ctx.bus.emit("conn-data", {
+        event: "disconnect",
+        direction: "tx",
+        instanceId: ctx.instanceId,
+        sessionId: msg.sessionId,
+        source: session.source || session.sourceCallsign,
+        destination: session.destination || session.destinationCallsign
+      });
+      ctx.bus.emit("conn-lifecycle", {
+        event: "disconnecting",
+        instanceId: ctx.instanceId,
+        sessionId: msg.sessionId
+      });
+      // Session removal and "disconnected" event fire when the TNC confirms with a d frame.
+      localSend(okEnvelope({ instanceId: ctx.instanceId, event: "disconnecting", sessionId: msg.sessionId }));
+      localDone();
+    });
+  }
+
+  RED.nodes.registerType("disconnect", DisconnectNode);
+};

package/nodes/encode.html

@@ -0,0 +1,117 @@
+<script type="text/javascript">
+RED.nodes.registerType("encode", {
+  category: "agwpe",
+  color: "#d4edda",
+  defaults: {
+    name: { value: "" },
+    source: { value: "" },
+    destination: { value: "" },
+    via: { value: "" },
+    control: { value: 3 },
+    pid: { value: 240 },
+    frameType: { value: "U" },
+    payload: { value: "" }
+  },
+  inputs: 1,
+  outputs: 1,
+  icon: "font-awesome/fa-compress",
+  label: function () {
+    return this.name || "encode";
+  }
+});
+</script>
+
+<script type="text/html" data-template-name="encode">
+  <div class="form-row">
+    <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+    <input type="text" id="node-input-name" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-source"><i class="fa fa-sign-in"></i> Source</label>
+    <input type="text" id="node-input-source" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-destination"><i class="fa fa-sign-out"></i> Destination</label>
+    <input type="text" id="node-input-destination" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-via"><i class="fa fa-random"></i> Via</label>
+    <input type="text" id="node-input-via" placeholder="WIDE1-1, WIDE2-1" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-control"><i class="fa fa-sliders"></i> Control</label>
+    <input type="number" id="node-input-control" min="0" max="255" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-pid"><i class="fa fa-hashtag"></i> PID</label>
+    <input type="number" id="node-input-pid" min="0" max="255" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-frameType"><i class="fa fa-filter"></i> Frame Type</label>
+    <select id="node-input-frameType">
+      <option value="I">I</option>
+      <option value="S">S</option>
+      <option value="U">U</option>
+    </select>
+  </div>
+  <div class="form-row">
+    <label for="node-input-payload"><i class="fa fa-file-text-o"></i> Payload</label>
+    <input type="text" id="node-input-payload" />
+  </div>
+</script>
+
+<script type="text/html" data-help-name="encode">
+  <p>Encodes structured AX.25 frame fields into raw bytes. Editor values are defaults;
+  incoming message properties override them when present.</p>
+
+  <h3>Input</h3>
+  <dl class="message-properties">
+    <dt>source <span class="property-type">string</span></dt>
+    <dd>Sending callsign (e.g. <code>"N0CALL-1"</code>). Overrides editor value.</dd>
+    <dt>destination <span class="property-type">string</span></dt>
+    <dd>Destination callsign (e.g. <code>"CQ"</code>). Overrides editor value.</dd>
+    <dt class="optional">via <span class="property-type">string | array</span></dt>
+    <dd>Digipeater path. A space- or comma-separated string (e.g. <code>"WIDE1-1 WIDE2-1"</code>)
+    or an array of callsign strings or <code>{callsign, hasBeenRepeated}</code> objects.
+    Overrides editor value. Omit or leave empty for no digipeaters.</dd>
+    <dt class="optional">control <span class="property-type">number</span></dt>
+    <dd>Raw control field byte (0–255). Takes precedence over <code>frameType</code> when both
+    are provided. Overrides editor value.</dd>
+    <dt class="optional">frameType <span class="property-type">string</span></dt>
+    <dd>Convenience shorthand for <code>control</code> when an exact byte is not needed.
+    <code>"I"</code> → <code>0x00</code>, <code>"S"</code> → <code>0x01</code>,
+    <code>"U"</code> → <code>0x03</code>. Ignored when <code>control</code> is also set.
+    Overrides editor value.</dd>
+    <dt class="optional">pid <span class="property-type">number</span></dt>
+    <dd>Protocol identifier byte (0–255). Defaults to <code>240</code> (<code>0xF0</code> — no layer 3).
+    Overrides editor value.</dd>
+    <dt class="optional">payload <span class="property-type">string | Buffer</span></dt>
+    <dd>Frame information field content. A string is encoded as UTF-8 bytes; a Buffer is used
+    as-is. Overrides editor value.</dd>
+    <dt class="optional">agwpePort <span class="property-type">number</span></dt>
+    <dd>AGWPE port byte. Passed through unchanged to the output message so the result can be
+    piped directly into <b>raw-out</b> without modification.</dd>
+  </dl>
+
+  <h3>Output</h3>
+  <dl class="message-properties">
+    <dt>status <span class="property-type">string</span></dt>
+    <dd><code>"ok"</code> on success; <code>"error"</code> if encoding fails. Check this field first.</dd>
+    <dt>event <span class="property-type">string</span></dt>
+    <dd>When <code>status</code> is <code>"ok"</code>: always <code>"encoded"</code>.</dd>
+    <dt>payload <span class="property-type">Buffer</span></dt>
+    <dd>When <code>status</code> is <code>"ok"</code>: the complete encoded AX.25 frame as raw bytes.
+    Can be passed directly to <b>raw-out</b> — it recognises the encode envelope and extracts
+    the nested payload automatically.</dd>
+    <dt class="optional">agwpePort <span class="property-type">number | null</span></dt>
+    <dd>When <code>status</code> is <code>"ok"</code>: AGWPE port byte passed through from the input,
+    or <code>null</code> if neither <code>msg.agwpePort</code> nor <code>msg.agwpePrefix</code>
+    was present.</dd>
+    <dt class="optional">errorCode <span class="property-type">string</span></dt>
+    <dd>When <code>status</code> is <code>"error"</code>: <code>ENCODE_INPUT_INVALID</code>
+    (source, destination, or control/frameType missing) or <code>ENCODE_FAILED</code>
+    (codec error during encoding).</dd>
+    <dt class="optional">errorText <span class="property-type">string</span></dt>
+    <dd>When <code>status</code> is <code>"error"</code>: human-readable description of the error.</dd>
+  </dl>
+</script>

package/nodes/encode.js

@@ -0,0 +1,164 @@
+"use strict";
+
+const codec = require("../lib/ax25-codec");
+const { okEnvelope, errorEnvelope } = require("../lib/message-utils");
+
+function splitCallsignList(value) {
+  return String(value || "")
+    .split(/[\s,]+/)
+    .map(function (item) {
+      return item.trim();
+    })
+    .filter(Boolean);
+}
+
+function normalizeViaInput(value) {
+  if (value === undefined || value === null || value === "") {
+    return undefined;
+  }
+
+  if (typeof value === "string") {
+    return splitCallsignList(value);
+  }
+
+  if (!Array.isArray(value)) {
+    return value;
+  }
+
+  const expanded = [];
+  value.forEach(function (entry) {
+    if (typeof entry === "string") {
+      splitCallsignList(entry).forEach(function (callsign) {
+        expanded.push(callsign);
+      });
+      return;
+    }
+
+    if (entry && typeof entry === "object" && typeof entry.callsign === "string") {
+      splitCallsignList(entry.callsign).forEach(function (callsign) {
+        expanded.push({
+          callsign,
+          hasBeenRepeated: Boolean(entry.hasBeenRepeated)
+        });
+      });
+      return;
+    }
+
+    expanded.push(entry);
+  });
+
+  return expanded;
+}
+
+function pickValue(msgValue, configValue) {
+  return msgValue !== undefined ? msgValue : configValue;
+}
+
+function parseByte(value) {
+  if (value === undefined || value === null || value === "") {
+    return undefined;
+  }
+
+  const numeric = typeof value === "number" ? value : Number(value);
+  if (!Number.isInteger(numeric) || numeric < 0 || numeric > 255) {
+    throw new Error("ENCODE_INVALID_BYTE");
+  }
+  return numeric;
+}
+
+function controlFromFrameType(frameType) {
+  const type = String(frameType || "").trim().toUpperCase();
+  if (!type) {
+    return undefined;
+  }
+  if (type === "I") {
+    return 0x00;
+  }
+  if (type === "S") {
+    return 0x01;
+  }
+  if (type === "U") {
+    return 0x03;
+  }
+  throw new Error("ENCODE_INVALID_FRAME_TYPE");
+}
+
+module.exports = function (RED) {
+  function EncodeNode(config) {
+    RED.nodes.createNode(this, config);
+    const node = this;
+
+    node.defaults = {
+      source: config.source !== undefined ? config.source : "N0CALL",
+      destination: config.destination !== undefined ? config.destination : "CQ",
+      via: config.via !== undefined ? config.via : "",
+      control: config.control !== undefined ? config.control : 3,
+      pid: config.pid !== undefined ? config.pid : 240,
+      frameType: config.frameType !== undefined ? config.frameType : "U",
+      payload: config.payload !== undefined ? config.payload : ""
+    };
+
+    node.on("input", function (msg, send, done) {
+      const localSend = send || function (m) {
+        node.send(m);
+      };
+      const localDone = done || function () {};
+
+      try {
+        const source = pickValue(msg.source, node.defaults.source);
+        const destination = pickValue(msg.destination, node.defaults.destination);
+        const via = normalizeViaInput(
+          pickValue(msg.via, node.defaults.via)
+        );
+        const frameType = pickValue(msg.frameType, node.defaults.frameType);
+        const control = parseByte(pickValue(msg.control, node.defaults.control));
+        const pid = parseByte(pickValue(msg.pid, node.defaults.pid));
+        const payloadInput = pickValue(msg.payload, node.defaults.payload);
+        const sourceHasBeenRepeated = pickValue(
+          msg.sourceHasBeenRepeated,
+          node.defaults.sourceHasBeenRepeated
+        );
+        const destinationHasBeenRepeated = pickValue(
+          msg.destinationHasBeenRepeated,
+          node.defaults.destinationHasBeenRepeated
+        );
+
+        const resolvedControl = control !== undefined ? control : controlFromFrameType(frameType);
+
+        if (!source || !destination || resolvedControl === undefined) {
+          localSend(
+            errorEnvelope(
+              "ENCODE_INPUT_INVALID",
+              "source, destination, and control/frameType are required"
+            )
+          );
+          localDone();
+          return;
+        }
+
+        const payload = codec.encode({
+          source,
+          destination,
+          sourceHasBeenRepeated,
+          destinationHasBeenRepeated,
+          via,
+          control: resolvedControl,
+          pid,
+          payload: payloadInput
+        });
+        localSend(okEnvelope({
+          event: "encoded",
+          agwpePort: msg.agwpePort !== undefined
+            ? msg.agwpePort
+            : (msg.agwpePrefix !== undefined ? msg.agwpePrefix : null),
+          payload
+        }));
+      } catch (error) {
+        localSend(errorEnvelope("ENCODE_FAILED", error.message));
+      }
+      localDone();
+    });
+  }
+
+  RED.nodes.registerType("encode", EncodeNode);
+};

package/nodes/monitor-in.html

@@ -0,0 +1,48 @@
+<script type="text/javascript">
+RED.nodes.registerType("monitor-in", {
+  category: "agwpe",
+  color: "#d4edda",
+  defaults: {
+    client: { value: "", type: "agwpe-client", required: true },
+    name: { value: "" }
+  },
+  inputs: 0,
+  outputs: 1,
+  icon: "font-awesome/fa-eye",
+  label: function () {
+    return this.name || "monitor-in";
+  }
+});
+</script>
+
+<script type="text/html" data-template-name="monitor-in">
+  <div class="form-row">
+    <label for="node-input-client"><i class="fa fa-server"></i> Client</label>
+    <input type="text" id="node-input-client" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+    <input type="text" id="node-input-name" />
+  </div>
+</script>
+
+<script type="text/html" data-help-name="monitor-in">
+  <p>Receives passive monitor traffic when monitor mode is enabled on agwpe-client.</p>
+  <p>Automatically binds to the AGWPE client node in the flow.</p>
+
+  <h3>Output</h3>
+  <dl class="message-properties">
+    <dt>status <span class="property-type">string</span></dt>
+    <dd>Always <code>"ok"</code>.</dd>
+    <dt>event <span class="property-type">string</span></dt>
+    <dd>Always <code>"monitor"</code>.</dd>
+    <dt>source <span class="property-type">string</span></dt>
+    <dd>Source callsign from the AX.25 header.</dd>
+    <dt>destination <span class="property-type">string</span></dt>
+    <dd>Destination callsign.</dd>
+    <dt>via <span class="property-type">array</span></dt>
+    <dd>Decoded digipeater objects (empty array if none).</dd>
+    <dt>payload <span class="property-type">Buffer</span></dt>
+    <dd>Frame information field bytes.</dd>
+  </dl>
+</script>

package/nodes/monitor-in.js

@@ -0,0 +1,42 @@
+"use strict";
+
+const { okEnvelope } = require("../lib/message-utils");
+
+module.exports = function (RED) {
+  function MonitorInNode(config) {
+    RED.nodes.createNode(this, config);
+    const node = this;
+
+    const cfg = RED.nodes.getNode(config.client);
+    const context = cfg ? cfg.instance : null;
+    if (!context) {
+      node.status({ fill: "red", shape: "ring", text: "client missing" });
+      return;
+    }
+
+    const onMonitorData = function (frame) {
+      if (!context.monitorEnabled) {
+        return;
+      }
+      node.send(
+        okEnvelope({
+          instanceId: context.instanceId,
+          event: "monitor",
+          payload: frame.payload,
+          source: frame.source,
+          destination: frame.destination,
+          via: frame.via || []
+        })
+      );
+    };
+
+    context.bus.on("monitor-data", onMonitorData);
+
+    node.on("close", function (removed, done) {
+      context.bus.off("monitor-data", onMonitorData);
+      done();
+    });
+  }
+
+  RED.nodes.registerType("monitor-in", MonitorInNode);
+};

package/nodes/raw-in.html

@@ -0,0 +1,50 @@
+<script type="text/javascript">
+RED.nodes.registerType("raw-in", {
+  category: "agwpe",
+  color: "#d4edda",
+  defaults: {
+    client: { value: "", type: "agwpe-client", required: true },
+    name: { value: "" }
+  },
+  inputs: 0,
+  outputs: 1,
+  icon: "font-awesome/fa-download",
+  label: function () {
+    return this.name || "raw-in";
+  }
+});
+</script>
+
+<script type="text/html" data-template-name="raw-in">
+  <div class="form-row">
+    <label for="node-input-client"><i class="fa fa-server"></i> Client</label>
+    <input type="text" id="node-input-client" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+    <input type="text" id="node-input-name" />
+  </div>
+</script>
+
+<script type="text/html" data-help-name="raw-in">
+  <p>Receives raw AX.25 bytes when raw mode is enabled.</p>
+  <p>Automatically binds to the AGWPE client node in the flow.</p>
+
+  <h3>Output</h3>
+  <dl class="message-properties">
+    <dt>status <span class="property-type">string</span></dt>
+    <dd>Always <code>"ok"</code>.</dd>
+    <dt>event <span class="property-type">string</span></dt>
+    <dd>Always <code>"raw"</code>.</dd>
+    <dt>source <span class="property-type">string</span></dt>
+    <dd>Source callsign decoded from the AX.25 header.</dd>
+    <dt>destination <span class="property-type">string</span></dt>
+    <dd>Destination callsign.</dd>
+    <dt>via <span class="property-type">array</span></dt>
+    <dd>Decoded digipeater objects from the AX.25 header (empty array if none).</dd>
+    <dt>agwpePort <span class="property-type">number</span></dt>
+    <dd>AGWPE port byte (0–255).</dd>
+    <dt>payload <span class="property-type">Buffer</span></dt>
+    <dd>Raw AX.25 frame bytes.</dd>
+  </dl>
+</script>

package/nodes/raw-in.js

@@ -0,0 +1,72 @@
+"use strict";
+
+const codec = require("../lib/ax25-codec");
+const { okEnvelope } = require("../lib/message-utils");
+
+module.exports = function (RED) {
+  function RawInNode(config) {
+    RED.nodes.createNode(this, config);
+    const node = this;
+
+    const cfg = RED.nodes.getNode(config.client);
+    const context = cfg ? cfg.instance : null;
+    if (!context) {
+      node.status({ fill: "red", shape: "ring", text: "client missing" });
+      return;
+    }
+
+    const onRawData = function (frame) {
+      if (!context.rawEnabled) {
+        return;
+      }
+
+      function normalizeAgwpePort(value) {
+        if (Buffer.isBuffer(value)) {
+          return value.length > 0 ? value.readUInt8(0) : 0;
+        }
+        const numeric = Number(value);
+        if (Number.isInteger(numeric) && numeric >= 0 && numeric <= 255) {
+          return numeric;
+        }
+        return 0;
+      }
+
+      // Strip leading AGWPE K-frame pad byte (0x00) that precedes the AX.25
+      // address chain in some AGWPE implementations.  Payload emitted to
+      // downstream nodes is the raw AX.25 wire frame only.
+      let rawPayload = frame.payload;
+      let agwpePort = normalizeAgwpePort(frame.agwpePort);
+      if (rawPayload.length > 1 && rawPayload[0] === 0x00 && rawPayload[1] >= 0x60) {
+        agwpePort = rawPayload.readUInt8(0);
+        rawPayload = rawPayload.subarray(1);
+      }
+
+      node.send(
+        okEnvelope({
+          instanceId: context.instanceId,
+          event: "raw",
+          payload: rawPayload,
+          agwpePort,
+          source: frame.source,
+          destination: frame.destination,
+          via: (function () {
+            try {
+              return codec.decodeWireAx25(rawPayload).via || [];
+            } catch (_) {
+              return [];
+            }
+          }())
+        })
+      );
+    };
+
+    context.bus.on("raw-data", onRawData);
+
+    node.on("close", function (removed, done) {
+      context.bus.off("raw-data", onRawData);
+      done();
+    });
+  }
+
+  RED.nodes.registerType("raw-in", RawInNode);
+};