Ethernet Gateway

A protocol-level walkthrough of how the gateway negotiates and moves data with the XMODEM family — the same code path serves XMODEM, XMODEM-1K, and YMODEM.

XMODEM (Ward Christensen, 1977) is the simplest of the file-transfer protocols the gateway speaks: a stop-and-wait, block-at-a-time scheme where the sender transmits one fixed-size block, waits for the receiver to acknowledge it, and only then sends the next. Every retro terminal program ever written understands it, which is why it is the lowest common denominator for moving files to and from a Commodore 64, a CP/M box, or an AltairDuino.

The gateway implements three members of the family on a single shared send/receive engine (src/xmodem.rs):

Two things are negotiated at the start of every transfer and are worth keeping straight: the error-check method (CRC-16 or the older 8-bit checksum) and, on receive, the block size (decided per block from the header byte). Both are covered in detail below.

The handful of bytes that drive the handshake.

The original. Each block is announced with SOH and carries exactly 128 bytes of payload. Small blocks mean a corrupted block is cheap to resend, which is why it survives on noisy links, but the per-block ACK round-trip caps throughput.

Identical framing, but each block is announced with STX and carries 1024 bytes — eight times the payload for the same header and one ACK round-trip, so it is markedly faster on a clean link. The two sizes can be mixed within one transfer: the receiver branches on the header byte (SOH vs STX) for every block, so a sender may stream 1K blocks and drop to a 128-byte block for a short final chunk.

XMODEM-1K plus metadata. Before the data, the sender transmits a block 0 — an SOH block whose block number is 0x00 (complement 0xFF) — whose 128-byte payload holds the filename, the exact file size, and optionally the modification time, all NUL-separated. Because the receiver learns the real size up front, it can truncate the file to the byte rather than guessing where the padding starts — which is the only way to receive a file that legitimately ends in 0x1A bytes (many binaries do) without corruption.

Two ways to detect a corrupted block — negotiated by the receiver's very first byte.

The choice is made entirely by which byte the receiver sends to start the transfer. A C says “I speak CRC-16, please use it”; a NAK says “fall back to the plain checksum.” CRC is strongly preferred — it catches error patterns a simple sum misses — so the gateway always asks for CRC first and only drops to checksum for genuinely ancient senders that never implemented it.

You send a file from your terminal to the gateway. The gateway is the receiver, so it drives the handshake.

From the File Transfer menu press U, type a filename, and choose X on the upload-protocol screen. The single X entry accepts plain XMODEM, XMODEM-1K, and YMODEM — the gateway auto-detects which one your terminal actually uses.

You pull a file from the gateway to your terminal. Here the gateway is the sender, so it waits for your terminal to drive the handshake.

Press D, pick the file from the numbered list, then choose the protocol. On download you select the variant explicitly, because the gateway must commit to a block size before it starts sending.

Exactly what goes on the wire for one block.

So a single CRC-mode block looks like this on the wire:

128-byte CRC block (133 bytes total):
  01  3C  C3  [ ...128 data bytes... ]  9A  7F
  ^   ^   ^                             ^^^^^^
  SOH #60 ~#60                          CRC-16

128-byte checksum block (132 bytes total):
  01  3C  C3  [ ...128 data bytes... ]  8E
  ^   ^   ^                             ^^
  SOH #60 ~#60                          sum

1024-byte CRC block (1029 bytes total):
  02  05  FA  [ ...1024 data bytes... ]  CRC CRC
  ^   ^   ^
  STX #5  ~#5

One shared set of keys covers XMODEM, XMODEM-1K, and YMODEM (they share the code path). Editable from the telnet Configuration → File Transfer menu, the GUI / web File Transfer → More… popup, or egateway.conf — changes apply on the next transfer, no restart.

Deep-dive reference pages for every protocol and interface, plus the character-set tables and ANSI escape-sequence reference.