# tncd — AGWPE-to-KISS Bridge

A userspace bridge that allows AGWPE-compatible client applications to communicate
with KISS TNCs (Terminal Node Controllers), including full AX.25 connected-mode
support. Developed because Linux kernel 7.1 removed native AX.25 kernel support,
breaking applications that previously relied on `AF_AX25` sockets.

## Purpose

Many packet radio programs — Winlink clients (PAT), APRS
applications (Xastir), and BBS software (Paracon) — talk to TNCs using
the AGWPE protocol. This bridge translates AGWPE to KISS and implements the AX.25
layer 2 state machine that a KISS TNC does not provide.

## Architecture

```
[AGWPE Client App] ----TCP----> [tncd] ----KISS----> [TNC Hardware]
(port 8000) (serial/TCP)
```

The bridge listens on port 8000 (configurable) for AGWPE client connections and
forwards frames to a KISS TNC via serial or TCP. Because KISS TNCs are dumb modems,
the bridge fully implements AX.25 connected mode: SABM/UA handshake, I-frame
sequencing, RR acknowledgement, duplicate detection, and clean DISC handling.

## Supported AGWPE Frame Types

| Kind | Direction | Description |
|------|-----------|-------------|
| `R` | RX/TX | Version query / response |
| `G` | RX/TX | Port info query / response |
| `g` | RX/TX | Port capabilities query / response |
| `X` | RX/TX | Register callsign |
| `x` | RX | Unregister callsign |
| `m` | RX | Enable frame monitoring |
| `y` | RX/TX | Outstanding frames query (per port) |
| `Y` | RX/TX | Outstanding frames query (per connection) — tracks unacked I-frames |
| `H` | RX/TX | Heard stations query |
| `K` | RX | Raw KISS frame passthrough |
| `k` | RX | Raw KISS mode toggle |
| `M` | RX | Send UI (unproto) frame |
| `V` | RX | Send UI frame via digipeaters |
| `C` | RX/TX | Connect / connected notification |
| `D` | RX/TX | Send / receive connected data |
| `d` | RX/TX | Disconnect / disconnected notification |
| `I` | TX | Monitor: received I-frame |
| `S` | TX | Monitor: received supervisory frame |
| `U` | TX | Monitor: received unnumbered frame |

## APRS and Unproto (UI) Frames

APRS and other unconnected-mode applications (Xastir, etc.) are fully supported.
UI frames do not require the AX.25 layer 2 state machine — the bridge passes them
directly between the AGWPE client and the KISS TNC:

- **Send** — `M` (UI frame) and `V` (UI frame via digipeaters) transmit APRS packets
- **Receive** — enable monitoring with `m`; received UI frames are delivered as `U`
monitor frames to all registered clients

No special configuration is needed; APRS and connected-mode (Winlink/PAT) clients
can share the same bridge instance simultaneously.

## AX.25 Connected Mode

The bridge fully implements AX.25 v2.0 connected mode for KISS TNCs:

- **SABM/UA handshake** — outgoing connections (PAT/Winlink) and incoming
- **I-frame sequencing** — N(S)/N(R) send/receive sequence numbers, mod 8 window
- **RR acknowledgement** — sends RR only when remote polls (P=1); does not flood
the channel with unsolicited RRs
- **Duplicate detection** — retransmitted I-frames from the remote are silently
discarded; only in-sequence frames are forwarded to the AGWPE client
- **AGWPE flow control** — `Y` (outstanding frames) accurately reflects unacked
I-frames so clients like PAT know when it is safe to send the next data block
- **TX echo suppression** — some TNCs (e.g. BTECH UV-Pro) echo transmitted frames
back via KISS; these are detected and discarded
- **DISC/DM handling** — clean disconnect in both directions