node-red-contrib-ax25 1.0.0

package/README.md

@@ -0,0 +1,317 @@
+# node-red-contrib-ax25
+
+Node-RED nodes for AX.25 packet radio connectivity via an AGWPE (AGW Packet Engine) server. Configure a connection to a local or remote AGWPE instance and use the provided nodes to establish connected sessions, exchange unconnected UI frames, monitor traffic, and encode/decode raw AX.25 frames — all from Node-RED flows without writing socket code.
+
+## Use cases
+
+### Connected mode — BBS and remote stations
+
+Use the `connect` and `send` nodes to establish an AX.25 connected session to a remote station such as a bulletin board system (BBS). The `connect` node sends the AX.25 connection request and emits lifecycle events and received data as the session progresses. Chain `send` nodes after it to exchange data: each `send` takes over the data output for the session so it receives the response to its own transmission. Use `waitFor` patterns to synchronize with BBS prompts without writing polling loops.
+
+```
+[inject connect] → [connect] → output 1: lifecycle events (connected / disconnected / timeout)
+                             → output 2: received data
+                                  ↓
+[inject "send payload"] → [send] → output 2: response to this sent payload
+                                ↓
+[inject] → [disconnect] → output 1: disconnecting event
+           (disconnected fires on [connect] output 1 when TNC confirms)
+```
+
+### APRS — UI frame monitoring and transmission
+
+APRS uses AX.25 UI (unconnected) frames. Enable raw mode on the `agwpe-client` config node and use `ui-in` to receive decoded APRS packets (source, destination, via path, payload) and `ui-out` to transmit UI frames. 
+
+Use `ui-in` and `ui-out` to quickly prototype/develop APRS services or gateways.  
+
+---
+
+## Installation
+
+```bash
+npm install node-red-contrib-ax25
+```
+
+Restart Node-RED. The nodes appear in the **agwpe** category in the palette.
+
+---
+
+## Nodes
+
+### agwpe-client (config node)
+
+Configure the AGWPE server connection in the Node-RED editor. The connection is established automatically when the flow deploys.
+
+Any software that exposes the AGWPE TCP interface works as a backend, including:
+
+- **[Direwolf](https://github.com/wb2osz/direwolf)** — software TNC for sound cards; widely used for APRS and packet radio on Linux, macOS, and Windows.
+- **[Soundmodem](https://uz7.ho.ua/packetradio.htm)** — UZ7HO's sound card TNC with AGWPE server support.
+- **[esp-tnc](https://github.com/n7get/esp-tnc)** — AX.25 router and BBS for ESP microcontrollers with AGWPE TCP server support.
+- **[go-ax25](https://github.com/n7get/go-ax25)** — Go library for AX.25.
+
+**Editor fields:**
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| Host | `127.0.0.1` | AGWPE server hostname or IP |
+| Port | `8000` | AGWPE server TCP port |
+| Callsigns | — | Comma-separated callsigns to register with AGWPE on connect |
+| Username / Password | — | Optional AGWPE credentials |
+| Monitor Mode | off | Enable monitor frame delivery to `monitor-in` nodes |
+| Raw Mode | off | Enable raw frame delivery to `raw-in` nodes and `ui-in` / `ui-out` |
+| Auto-Reconnect | on | Automatically reconnect after a dropped connection |
+| Reconnect Delay | `5000` ms | Delay before each reconnect attempt |
+
+The `connect`, `ui-out`, `ui-in`, `monitor-in`, `raw-out`, and `raw-in` nodes each select which `agwpe-client` to bind to using a **Client** dropdown in their editor. The `send` node does not need a client selection — it gets the `agwpe-client` from the `sessionId`.
+
+---
+
+### connect
+
+Establishes an AX.25 connected session to a remote station.
+
+**Input:** any message with `msg.destination` set (or configured in the node editor).
+
+```json
+{ "destination": "N0CALL-1" }
+```
+
+`source` defaults to the first callsign registered on the `agwpe-client`. `destination` can also be set in the node editor and overridden per-message. `via` accepts a comma-separated string, array of strings, or array of `{ callsign, hasBeenRepeated }` objects.
+
+```json
+{ "source": "N0CALL", "destination": "N0CALL-1", "via": "RELAY" }
+```
+
+**Output 1 — lifecycle events** (`msg.event`):
+
+| Event | Meaning |
+|-------|---------|
+| `connecting` | Connect request sent |
+| `connected` | Remote station accepted |
+| `disconnecting` | Disconnect in progress |
+| `disconnected` | Session closed |
+| `timeout` | No activity (sent or received) within timeout period |
+| `failed` | Transport or session error |
+
+**Output 2 — received data:**
+
+Controlled by the **Mode** editor field (default: `line`):
+
+- **line mode** — incoming bytes are buffered and split on CR or CR+LF. Each complete line is emitted as `msg.payload` (string). If `waitFor` is set (a regex string), lines accumulate until one matches; `msg.payload` is then an array of the preceding lines and `msg.match` is the matching line. On timeout, `msg.event: "timeout"` is emitted on output 1 with the current buffer contents.
+- **binary mode** — each received frame is emitted immediately with `msg.payload` as a Buffer.
+
+`mode`, `waitFor`, `timeout`, `source`, `destination`, and `via` can all be set in the node editor and overridden per-message with the corresponding `msg` properties.
+
+The `sessionId` assigned to the session is included on every output message and must be passed to subsequent `send` commands.
+
+---
+
+### send
+
+Sends data on an established session. When a `send` node processes an input message, it takes over the data output (output 2) for that session so it receives the response to its own transmission.
+
+The `send` node gets the correct `agwpe-client` at runtime from the `sessionId`, so it works with any session from any client automatically.
+
+**Input:**
+
+```json
+{ "sessionId": "sess-abc", "payload": "HELLO\r" }
+```
+
+`payload` may be a string or a Buffer. Arrays of strings/Buffers are also accepted; each item is sent as a separate frame. Payloads longer than 255 bytes are segmented automatically.
+
+**Output 1** — lifecycle events (same structure as `connect` output 1).  
+**Output 2** — received data (same line/binary behaviour as `connect`; `waitFor` and `timeout` can be set in the node editor or per-message).
+
+---
+
+### disconnect
+
+Initiates a graceful disconnect for an established session. 
+
+**Input:** any message with `msg.sessionId` set.
+
+```json
+{ "sessionId": "sess-abc" }
+```
+
+**Output 1** — emits `disconnecting` immediately on success, or `SESSION_NOT_FOUND` on error. The `disconnected` event fires on the originating `connect` node's output 1 once the TNC confirms with a `d` frame.
+
+---
+
+### ui-out
+
+Encodes and transmits an AX.25 UI frame via the AGWPE raw (K-frame) transport. **Raw mode must be enabled** on the `agwpe-client`.
+
+Set `source`, `destination`, `via`, and `payload` in the node editor. Any triggering message causes the frame to be sent; individual fields can be overridden per-message:
+
+```json
+{ "payload": "status text" }
+```
+
+`via` accepts the same formats as `connect`. `msg.agwpePort` overrides the AGWPE port byte (default `0`).
+
+Output: a single message with `event: "ui-sent"` on success, or an error envelope on failure.
+
+---
+
+### ui-in
+
+Receives AGWPE raw (K-frame) traffic, decodes the embedded AX.25 UI frames, and emits one message per frame. **Raw mode must be enabled** on the `agwpe-client`.
+
+Output message fields: `source`, `destination`, `via` (array of callsigns), `payload`.
+
+The **Payload Output** editor option selects `string` (UTF-8, default) or `buffer` (raw bytes).
+
+Non-UI frames are silently discarded.
+
+---
+
+### monitor-in
+
+Receives all frames seen by the AGWPE server in monitor mode. **Monitor mode must be enabled** on the `agwpe-client`.
+
+Output: one message per frame with `source`, `destination`, `payload`, and AGWPE frame metadata.
+
+---
+
+### raw-out
+
+Transmits a raw AX.25 frame inside an AGWPE K-frame. **Raw mode must be enabled.**
+
+`msg.payload` accepts:
+
+- `Buffer`
+- `Uint8Array`
+- byte array (numbers 0–255)
+- hex string (`"82 a0 a8"` or `"82a0a8"`)
+
+`msg.agwpePort` (or the editor **AGWPE Port** field, default `0`) sets the leading port byte of the K-frame.
+
+---
+
+### raw-in
+
+Receives raw AGWPE K-frames. **Raw mode must be enabled.**
+
+Output: `msg.payload` is a Buffer of the raw AX.25 wire bytes (leading AGWPE port byte stripped and exposed separately as `msg.agwpePort`).
+
+---
+
+### decode
+
+Decodes a raw AX.25 frame Buffer into its constituent fields.
+
+**Input:** `msg.payload` must be a Buffer containing AX.25 wire bytes (e.g. from `raw-in`).
+
+**Output:**
+
+```json
+{
+  "source": "N0CALL",
+  "destination": "CQ",
+  "via": [{ "callsign": "WIDE1-1", "hasBeenRepeated": false }],
+  "control": 3,
+  "pid": 240,
+  "payload": "decoded payload here"
+}
+```
+
+The **Payload Output** editor option selects `string` (UTF-8, default) or `buffer`.
+
+---
+
+### encode
+
+Encodes structured fields into a raw AX.25 frame Buffer. Editor defaults are pre-set for a UI frame (control `0x03`, PID `0xF0`). All fields can be overridden per-message.
+
+**Input fields** (message overrides editor defaults):
+
+| Field | Example | Notes |
+|-------|---------|-------|
+| `source` | `"N0CALL"` | |
+| `destination` | `"CQ"` | |
+| `via` | `"WIDE1-1,WIDE2-1"` | string, array of strings, or array of `{callsign, hasBeenRepeated}` |
+| `control` | `3` | byte value, or use `frameType` (`"U"`, `"I"`, `"S"`) |
+| `pid` | `240` | byte value |
+| `payload` | `"text"` | string or Buffer |
+
+**Output:** `msg.payload` is the encoded AX.25 frame as a Buffer, ready to pass to `raw-out`.
+
+---
+
+## Examples
+
+Ready-to-import flows are provided in the [`examples/`](examples/) directory. Import any `.json` file via **Menu → Import** in the Node-RED editor.
+
+---
+
+### Beacons
+
+**File:** [`examples/beacons.json`](examples/beacons.json)
+
+![Beacons flow](examples/beacons.png)
+
+Receives and transmits AX.25 UI frames using the `ui-in` and `ui-out` nodes. Demonstrates APRS-style beacon monitoring and periodic transmission.
+
+---
+
+### Send message test
+
+**File:** [`examples/send_test_message.json`](examples/send_test_message.json)
+
+![Send message test flow](examples/send_test_message.png)
+
+A complete flow that connects to a packet BBS, composes and sends a test message using the **Send message** subflow, and disconnects via the **Bye** subflow. Demonstrates end-to-end message delivery from connection through graceful teardown.
+
+---
+
+### Send message subflow
+
+**File:** [`examples/send_message_subflow.json`](examples/send_message_subflow.json)
+
+![Send message subflow](examples/send_message_subflow.png)
+
+A reusable subflow that composes and sends a message to a packet BBS: sets the addressee, subject, and body via a sequence of `send` nodes, each waiting for the BBS prompt before advancing.
+
+---
+
+### Get message list subflow
+
+**File:** [`examples/get_message_list_subflow.json`](examples/get_message_list_subflow.json)
+
+![Get message list subflow](examples/get_message_list_subflow.png)
+
+A reusable subflow that retrieves the message list from a packet BBS using the `send` / `waitFor` pattern and returns a parsed list.
+
+---
+
+### Delete all my messages
+
+**File:** [`examples/delete_all_my_messages.json`](examples/delete_all_my_messages.json)
+
+![Delete all my messages flow](examples/delete_all_my_messages.png)
+
+A full flow that connects to a packet BBS, retrieves the message list using the **Get message list** subflow, deletes every message addressed to the registered callsign, and disconnects cleanly. Demonstrates composing subflows into a complete automated task.
+
+---
+
+### Bye subflow
+
+**File:** [`examples/bye_subflow.json`](examples/bye_subflow.json)
+
+![Bye subflow](examples/bye_subflow.png)
+
+A reusable subflow that sends a `BYE` command and waits for the BBS to close the session gracefully. Intended to be composed into larger BBS flows.
+
+---
+
+## Testing
+
+```bash
+npm test
+```
+## TODO
+
+Implement `listen` and `accept` nodes for creating AX.25 servers.
+

package/examples/beacons.json

@@ -0,0 +1,130 @@
+[
+    {
+        "id": "65a0d887c03a3e96",
+        "type": "tab",
+        "label": "Beacons",
+        "disabled": false,
+        "info": "",
+        "env": []
+    },
+    {
+        "id": "a4494b4c19e5a930",
+        "type": "ui-in",
+        "z": "65a0d887c03a3e96",
+        "client": "9563d0689b7ce1af",
+        "name": "",
+        "payloadOutput": "string",
+        "x": 164,
+        "y": 100,
+        "wires": [
+            [
+                "799c276c66fa1dce"
+            ]
+        ]
+    },
+    {
+        "id": "24e57122cb89257d",
+        "type": "debug",
+        "z": "65a0d887c03a3e96",
+        "name": "debug 1",
+        "active": true,
+        "tosidebar": true,
+        "console": true,
+        "tostatus": false,
+        "complete": "true",
+        "targetType": "full",
+        "statusVal": "",
+        "statusType": "auto",
+        "x": 564,
+        "y": 100,
+        "wires": []
+    },
+    {
+        "id": "799c276c66fa1dce",
+        "type": "function",
+        "z": "65a0d887c03a3e96",
+        "name": "function 2",
+        "func": "\nconst vias = msg.via.map( v => v.callsign + (v.hasBeenRepeated ? '*' : '') ).join(' ');\n\nreturn {\n    source: msg.source,\n    destination: msg.destination,\n    vias,\n    payload: msg.payload,\n};",
+        "outputs": 1,
+        "timeout": 0,
+        "noerr": 0,
+        "initialize": "",
+        "finalize": "",
+        "libs": [],
+        "x": 354,
+        "y": 100,
+        "wires": [
+            [
+                "24e57122cb89257d"
+            ]
+        ]
+    },
+    {
+        "id": "69164145ed38640a",
+        "type": "inject",
+        "z": "65a0d887c03a3e96",
+        "name": "",
+        "props": [],
+        "repeat": "",
+        "crontab": "",
+        "once": false,
+        "onceDelay": 0.1,
+        "topic": "",
+        "x": 190,
+        "y": 180,
+        "wires": [
+            [
+                "3207efd50fdb02f8"
+            ]
+        ]
+    },
+    {
+        "id": "3207efd50fdb02f8",
+        "type": "ui-out",
+        "z": "65a0d887c03a3e96",
+        "client": "9563d0689b7ce1af",
+        "name": "",
+        "source": "N0CALL-7",
+        "destination": "APX100",
+        "via": "WIDE1-1,WIDE2-1",
+        "payload": "!3612.97N/11517.07W-node-red-contrib-ax25 test",
+        "x": 350,
+        "y": 180,
+        "wires": [
+            [
+                "de2571a8cf9037f8"
+            ]
+        ]
+    },
+    {
+        "id": "de2571a8cf9037f8",
+        "type": "debug",
+        "z": "65a0d887c03a3e96",
+        "name": "debug 7",
+        "active": true,
+        "tosidebar": true,
+        "console": true,
+        "tostatus": false,
+        "complete": "true",
+        "targetType": "full",
+        "statusVal": "",
+        "statusType": "auto",
+        "x": 550,
+        "y": 180,
+        "wires": []
+    },
+    {
+        "id": "9563d0689b7ce1af",
+        "type": "agwpe-client",
+        "name": "",
+        "host": "192.168.68.20",
+        "port": 8000,
+        "callsigns": "N0CALL",
+        "username": "",
+        "password": "",
+        "monitor": false,
+        "raw": true,
+        "reconnect": true,
+        "reconnectDelay": 5000
+    }
+]

package/examples/bye_subflow.json

@@ -0,0 +1,107 @@
+[
+    {
+        "id": "f1e3c30bea1bbe94",
+        "type": "subflow",
+        "name": "Bye",
+        "info": "",
+        "category": "",
+        "in": [
+            {
+                "x": 80,
+                "y": 120,
+                "wires": [
+                    {
+                        "id": "0813fedcec47e075"
+                    }
+                ]
+            }
+        ],
+        "out": [],
+        "env": [],
+        "meta": {},
+        "color": "#DDAA99"
+    },
+    {
+        "id": "0813fedcec47e075",
+        "type": "function",
+        "z": "f1e3c30bea1bbe94",
+        "name": "B",
+        "func": "\"use strict\";\n\nif (!msg.sessionId) {\n  const errorCode = 'NO_SESSION_ID';\n  const errorText = \"sessionID not found\";\n\n  node.error(`[${errorCode}] ${errorText}`);\n\n  return [{\n    status: 'error',\n    errorCode,\n    errorText,\n    msg,\n  }, null];\n}\n\nreturn [null, {\n    sessionId: msg.sessionId,\n    command: 'send',\n    payload: 'B',\n  timeout: 30000,\n}];\n",
+        "outputs": 2,
+        "timeout": 0,
+        "noerr": 0,
+        "initialize": "",
+        "finalize": "",
+        "libs": [],
+        "x": 210,
+        "y": 120,
+        "wires": [
+            [
+                "637170b1c7227488"
+            ],
+            [
+                "1e49e3218b1dd308"
+            ]
+        ]
+    },
+    {
+        "id": "1e49e3218b1dd308",
+        "type": "send",
+        "z": "f1e3c30bea1bbe94",
+        "name": "",
+        "timeout": "",
+        "waitFor": "",
+        "x": 390,
+        "y": 160,
+        "wires": [
+            [
+                "e3ab85e4461b92a5"
+            ],
+            [
+                "fed58202ceb48e13"
+            ]
+        ]
+    },
+    {
+        "id": "e3ab85e4461b92a5",
+        "type": "function",
+        "z": "f1e3c30bea1bbe94",
+        "name": "check error",
+        "func": "\"use strict\";\n\nif (msg.status === 'error') {\n    node.error(`[${msg.errorCode}] ${msg.errorText}`, msg);\n    return msg;\n}\nreturn null;",
+        "outputs": 1,
+        "timeout": 0,
+        "noerr": 0,
+        "initialize": "",
+        "finalize": "",
+        "libs": [],
+        "x": 610,
+        "y": 140,
+        "wires": [
+            [
+                "fed58202ceb48e13"
+            ]
+        ]
+    },
+    {
+        "id": "fed58202ceb48e13",
+        "type": "disconnect",
+        "z": "f1e3c30bea1bbe94",
+        "name": "",
+        "x": 810,
+        "y": 180,
+        "wires": [
+            []
+        ]
+    },
+    {
+        "id": "637170b1c7227488",
+        "type": "disconnect",
+        "z": "f1e3c30bea1bbe94",
+        "name": "",
+        "x": 410,
+        "y": 80,
+        "wires": [
+            []
+        ]
+    }
+]