ax25.js/README.md

ax25.js — AX.25 + HDLC utilities (TypeScript)

This repository provides low-level utilities for AX.25 frame construction/parsing and HDLC framing used in amateur radio applications. It's intentionally small and focused on framing, FCS and control-field helpers.

Highlights

• Address – create and parse callsigns, produce 7-byte AX.25 address fields.
• Frame – InformationFrame, SupervisoryFrame, UnnumberedFrame and Frame.fromBytes() parsing.
• Control builders: buildIControl, buildSControl, buildUControl (and extended 2‑byte builders).
• Encoders: encodeFrame, convenience encodeAx25 / alias encodeAX25.
• HDLC: encodeHDLC, escapeBuffer, unescapeBuffer, computeFcs / crc16Ccitt, verifyAndStripFcs.
• Convenience stream helpers: toHDLC, toWire, toWireStream.
• FX25 class: detection heuristics; full FEC decoding (Reed–Solomon) is a TODO.

Install & tests

npm install
npm test

Examples

Note: during development you can import directly from src/*. When published, import from the package entrypoint.

Address

import { Address } from './src/address';

const a = Address.fromString('N0CALL-0');
console.log(a.toString()); // N0CALL-0

Build an AX.25 UI payload and HDLC-wrap it

import { Address } from './src/address';
import { UnnumberedFrame, encodeFrame, encodeAX25, toHDLC } from './src/frame';

const src = Address.fromString('SRC-1');
const dst = Address.fromString('DST-0');
const info = new TextEncoder().encode('payload');

// quick builder
const ax = encodeAX25(dst, src, info, { ui: true });

// or construct Frame and HDLC-wrap
const f = new UnnumberedFrame(src, dst, 0x03, 'UI', 0, info);
const hdlc = toHDLC(f); // includes FCS, escapes and flags

Parsing

import { Frame } from './src/frame';

const frame = Frame.fromBytes(ax);
console.log(frame.toString());

HDLC & FCS

• computeFcs(payload) — CRC-16-CCITT with AX.25/X.25 inversion semantics.
• encodeHDLC(payload, { includeFcs: true }) — wraps payload with 0x7E flags, appends FCS and escapes special bytes.
• verifyAndStripFcs(buf) — validates and strips a little-endian 2-byte FCS from a buffer.

Testing and style

• Tests live in test/ and are run with Vitest. They follow describe('Class.method', ...) naming.
• Keep tests targeted and add coverage for new behavior.