Ethernet Gateway

ZMODEM (Chuck Forsberg, 1988) is the modern, streaming, batch-capable evolution of the XMODEM family — and the one most terminal programs start automatically.

Where XMODEM and YMODEM send one fixed block and wait for an acknowledgement, ZMODEM is built around frames and subpackets with position-based recovery: data is identified by its byte offset in the file, so the receiver recovers from an error by telling the sender where to resume rather than which block to resend. It adds, over YMODEM:

• CRC-32 (as well as CRC-16) for far stronger error detection.
• ZDLE escaping so the stream survives links that eat control bytes or XON/XOFF flow control.
• Autostart — the sender can kick off a transfer from any menu; the gateway detects it and switches to receive.
• Crash recovery / resume via ZRPOS, and per-file skip via ZSKIP in a batch.

The gateway implements the full Forsberg 1988 spec in src/zmodem.rs: ZDLE escaping, hex / binary16 / binary32 headers, CRC-16 and CRC-32, and batch send and receive. Its ZRINIT advertises CANFDX | CANOVIO | CANFC32 (full-duplex, overlapped I/O, CRC-32 capable), but the data path runs stop-and-wait — every non-final data subpacket is ZCRCQ-terminated and ACK-gated (the final one closes the frame with ZCRCE). That is slightly slower than true streaming in theory, but rock-solid over a telnet or SSH hop where buffering and flow control are unpredictable.

Everything on the wire is either a header or a data subpacket.

A header carries a frame type plus a 4-byte argument (a file position, a capability mask, a length). It comes in three encodings, all introduced by the ZPAD ZDLE sync (* * 0x18 …), which is also what makes autostart possible:

The A / B / C suffix is exactly what the autostart prefix **\x18[ABC] encodes.

Data rides in subpackets; the byte that ends each one tells the receiver what to do next. The gateway sends data using ZCRCQ (ACK-gated) between subpackets and ZCRCE on the last, which is what gives it its safe stop-and-wait cadence.

How ZMODEM keeps control bytes from being eaten by the link.

ZDLE (ZMODEM Data Link Escape, 0x18 — the same byte as CAN) is the escape marker. Any byte in the data or CRC that could be intercepted by the transport — ZDLE itself, DLE (0x10), the XON/XOFF flow-control pair (0x11 / 0x13) and their high-bit twins (0x91 / 0x93), and CR (0x0D, and its high-bit twin 0x8D) — is rewritten on the wire as ZDLE followed by the byte with bit 6 flipped (byte XOR 0x40). The receiver reverses the transform.

This is why ZMODEM survives XON/XOFF-flow-controlled serial links and telnet hops that would choke on a raw 0x11: those bytes never appear literally in the escaped stream. (Over telnet the gateway additionally handles the 0xFF IAC transform; ZDLE and IAC escaping are independent layers.)

A receiver can ask the sender to escape more than that default set by setting ESCCTL (escape every control character) or ESC8 (escape every 8th-bit byte) in its ZRINIT capability flags — the gateway honors both when it is the sender. On decode it also accepts the legacy ZRUB0 / ZRUB1 rubout escapes (a sender's alternate encoding of 0x7F / 0xFF). And because ZDLE is the same byte as CAN, a run of them is how a peer signals abort: the gateway treats five or more consecutive CANs (or a ZDLE CAN pair) as an immediate cancel rather than waiting out a timeout.

You pull a file from the gateway. The gateway sends; your terminal's receiver drives the conversation with ZRINIT / ZRPOS.

The single-file handshake (the ZFILE → ZEOF cycle repeats per file in a batch):

gateway  -> ZRQINIT                       open the session
term     <- ZRINIT (CANFDX|CANOVIO|CANFC32)  receiver ready + caps
gateway  -> ZFILE + subpacket("name\0size\0", ZCRCW)
term     <- ZRPOS(0)                     accept; start at byte 0
gateway  -> ZDATA(0) + 1024-byte subpackets (ZCRCQ, ACK-gated; final ZCRCE) ... until EOF
gateway  -> ZEOF(length)                 final file size
term     <- ZRINIT                       ready for next file
gateway  -> ZFIN
term     <- ZFIN
gateway  -> "OO"                          over and out

You send a file to the gateway. The gateway receives, so it drives with ZRINIT / ZRPOS / ZSKIP.

gateway  -> ZRINIT (CANFDX|CANOVIO|CANFC32)  ready + caps
term     <- ZFILE + subpacket("name\0size\0")
gateway  -> ZRPOS(0)   accept   (or ZSKIP to decline a colliding name)
term     <- ZDATA + data subpackets ... 
gateway  -> ZRPOS(offset)                 only on a CRC error: rewind
term     <- ZEOF(length)
gateway  -> ZRINIT                        ready for next file
term     <- ZFIN
gateway  -> ZFIN
term     <- "OO"

A batch is the ZFILE → ZDATA → ZEOF cycle repeated once per file, with the receiver answering ZRINIT after each ZEOF to signal “ready for the next.” The single ZFIN / ZFIN / "OO" exchange closes the whole session. Either side can decline an individual file with ZSKIP without aborting the batch.

Most terminals (Qodem, ZOC, SyncTERM, ExtraPuTTY) begin a ZMODEM send by emitting the autostart sequence — **\x18B, **\x18A, or **\x18C (a hex / binary16 / binary32 ZRQINIT) — directly into whatever menu the user is sitting at, expecting the far end to “just receive.” The gateway's idle input loop watches for that ZPAD ZPAD ZDLE prefix and, on a match:

1. logs “ZMODEM autostart detected; switching to receive,”
2. drains any residual ZRQINIT bytes (the sender re-sends once we ZRINIT),
3. hands off to the normal receive flow — using the sender's filename after path validation, applying mtime / mode if present,
4. and returns to whichever menu the user was on when the transfer fired.

ZMODEM has its own independent timeout set (separate from the XMODEM family). 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.