YMODEM Protocol Reference — Ethernet Gateway v0.6.2

Overview

YMODEM is XMODEM-1K with a name tag and a guest list — it adds a metadata header and batch transfers on top of the same block engine.

YMODEM (Chuck Forsberg, building on Ward Christensen's XMODEM) keeps XMODEM-1K's exact block framing and CRC-16 error checking and adds two things on top:

A block 0 sent before the data, carrying the filename, the exact byte size, and optionally the modification time and permission bits.
Batch transfer — several files in one session, each introduced by its own block 0, terminated by a special empty “end-of-batch” block 0.

Because the receiver learns the real size up front, it can truncate the saved file to the exact byte instead of guessing where the padding starts — the one reliable way to receive a file that genuinely ends in 0x1A bytes without corruption. The gateway runs all of this on the same send/receive engine as XMODEM (src/xmodem.rs).

Read the XMODEM page first. The block framing (SOH/STX headers, block numbers and complements, the stop-and-wait ACK/NAK loop) and CRC-16 vs. checksum mechanics are covered in detail on the XMODEM Protocol Reference. YMODEM uses CRC-16 (the receiver opens with C) and 1024-byte STX data blocks; this page focuses on what YMODEM adds — block 0, batch, and metadata.

The Block 0 Header

A normal-looking XMODEM block, number zero, whose payload is metadata instead of file data.

Block 0 is framed exactly like any other 128-byte XMODEM block — SOH, a block number, its complement, 128 payload bytes, and a 2-byte CRC-16 — but the block number is 0x00 (complement 0xFF), which is how the receiver recognizes it. The 128-byte payload is an ASCII string:

filename\0length modtime mode 0\0[ NUL padding to 128 bytes ]

Field	Format	Notes
filename	ASCII, `NUL`-terminated	Mandatory. Path-validated on receive (no traversal).
length	decimal	Mandatory. The exact file size in bytes — drives truncation.
modtime	octal	Optional. UNIX seconds since the epoch. `0` = unknown.
mode	octal	Optional. UNIX permission bits (e.g. `100644`).
serial	octal	Always `0` — vestigial, ignored.

So a real block-0 payload for a 1024-byte file looks like:

68 65 6C 6C 6F 2E 62 69 6E 00   "hello.bin\0"
31 30 32 34 20 ...               "1024 13507362625 100644 0\0"
00 00 00 ...                     /dev/null fill to 128 bytes
9A 7F                            CRC-16

Minimal senders welcome. The parser is lenient: a block 0 with just filename\0length\0 (no modtime/mode) is accepted, junk after the size is tolerated, and a modtime of 0 is treated as “unknown” rather than 1970.

Upload — Gateway as Receiver

You send a file from your terminal to the gateway with YMODEM. The gateway receives, so it drives the handshake.

Step 1 — Start the upload

From the File Transfer menu press U, type a filename, and pick X on the upload-protocol screen. The single X entry auto-detects plain XMODEM, XMODEM-1K, and YMODEM — YMODEM is recognized the moment a block 0 arrives.

Step 2 — Request CRC, then read block 0

Filename and size arrive first

The gateway sends C (0x43) to request CRC-16, repeating it on the retry interval until the sender responds (full handshake details on the XMODEM page).
The first block arrives as SOH with block number 0x00 and complement 0xFF — a block 0.
The gateway reads the 128-byte payload, validates its CRC-16, and parses the filename and exact size (and modtime / mode if present).
It sends ACK (0x06) to accept block 0, then a second C to start the data phase.

Step 3 — Receive the data blocks

Identical to XMODEM-1K from here

Data blocks are numbered from 1: STX for 1024-byte blocks (the YMODEM norm) or SOH for a 128-byte block, decided per block from the header byte.
Each block is validated (complement, CRC-16, sequence) and ACK'd — the same stop-and-wait recovery as XMODEM: a corrupt block is NAK'd and resent (bounded by xmodem_max_retries), a duplicate is re-ACK'd, an inter-block timeout re-prompts with NAK, and a valid block with a non-duplicate sequence number cancels with CAN.

Step 4 — End of file, then end of batch

EOT and the closing block 0

The sender transmits EOT (0x04); the gateway answers with ACK.
The gateway then sends one more C and reads the end-of-batch block 0 — a block 0 whose filename is empty — which signals “no more files.” The gateway ACKs it and the session ends.

Step 5 — Save with exact size and metadata

Truncate, then stamp

The file is truncated to the exact length from block 0 — no SUB stripping, so trailing 0x1A bytes survive intact.
If block 0 carried a non-zero modtime, it is applied to the saved file (best-effort).
If it carried a mode, the permission bits are applied, masked to 0o777 so a sender can't set setuid / setgid / sticky bits.

Download — Gateway as Sender

You pull a file from the gateway with YMODEM. The gateway sends, so it waits for your terminal to drive the handshake.

Step 1 — Pick the file and YMODEM

Press D, choose the file from the numbered list, and press Y on the protocol screen.

------------------------------------

SELECT PROTOCOL

------------------------------------

X XMODEM 128-byte blocks

1 XMODEM-1K 1024-byte blocks

Y YMODEM name+size hdr, 1K

Z ZMODEM autostart, 1K

K KERMIT any flavor, auto

P PUNTER C1 CCGMS/Novaterm

Step 2 — Wait for the CRC request

The gateway waits for the receiver's C (0x43), which both starts the transfer and confirms CRC-16. (YMODEM is a CRC protocol; the checksum fallback that plain XMODEM offers does not apply.)

Step 3 — Send block 0

Announce the file

The gateway builds block 0: SOH, number 0x00, complement 0xFF, payload filename\0length modtime mode 0\0 (length decimal, modtime & mode octal), NUL-padded to 128 bytes, CRC-16.
It sends block 0 and waits for the receiver's ACK followed by a C — together these start the data phase.

Step 4 — Stream the data blocks

1K blocks, one ACK each

Data blocks are numbered from 1 and sent as 1024-byte STX blocks.
The gateway may drop to a 128-byte SOH block for a short final chunk rather than padding a whole 1K block; the last block is filled to size with SUB (0x1A) when needed.
After each block it waits for ACK; a NAK or a read timeout makes it resend the same block, up to the retry cap.

Step 5 — EOT and end of batch

Close the file, then the batch

After the last data block the gateway sends EOT (0x04). Per the classic spec the receiver may NAK the first EOT; the gateway resends it and completes on the ACK.
The receiver sends a final C; the gateway answers with the end-of-batch block 0 (empty filename) to signal “no more files,” and the transfer ends once it is ACK'd.

Batch & End-of-Batch

How YMODEM moves more than one file in a single session.

A YMODEM batch is just block 0 / data / EOT repeated, once per file, with a single empty block 0 to close the session. On the wire a two-file batch looks like:

C                            receiver requests CRC
[block 0: "a.bin" 512]       file 1 header  -> ACK, C
[data blocks 1..N] EOT       file 1 data    -> ACK
C                            receiver ready for next
[block 0: "b.bin" 2048]      file 2 header  -> ACK, C
[data blocks 1..M] EOT       file 2 data    -> ACK
C                            receiver ready for next
[block 0: "" (empty)]        END OF BATCH   -> ACK

The empty-filename block 0 is the terminator: a block 0 whose payload starts with a NUL tells the receiver there are no more files, and the session ends cleanly.

Metadata & Truncation

From block 0	On receive (gateway saves)
length (size)	The file is truncated to exactly this many bytes — trailing `0x1A` bytes are preserved (unlike plain XMODEM, which SUB-strips).
modtime	Applied to the saved file's modification time (best-effort; a value of `0` or absent means leave it as “now”).
mode	Applied as permission bits on Unix, masked to `0o777` (setuid / setgid / sticky bits are stripped for safety); ignored on non-Unix.
filename	Path-validated (no traversal, length cap). On download the gateway emits the file's real name, size, mtime, and mode.

Why size beats SUB-stripping: plain XMODEM and XMODEM-1K have no length field, so the receiver removes trailing 0x1A padding and hopes the file didn't really end in those bytes. YMODEM's exact size makes that guess unnecessary — which is why it is the right choice for binaries, archives, and disk images.

Tunables

YMODEM shares one set of timeout keys with XMODEM and XMODEM-1K (they are one 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.

Key	Default	Meaning
`xmodem_negotiation_timeout`	45 s	How long to wait for the far end to start.
`xmodem_negotiation_retry_interval`	7 s	Gap between `C` pokes during the handshake.
`xmodem_block_timeout`	20 s	Per-block read deadline once the transfer is live.
`xmodem_max_retries`	10	Resends of one block before giving up.

See also: the XMODEM Protocol Reference for the underlying block framing and CRC-16 / checksum mechanics, the File Transfer section of the User Manual for the menu walkthrough, and the Kermit Reference for the 7-bit-clean alternative with its own batch + attribute support.

References

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

XMODEM

128-byte blocks; CRC-16 / checksum negotiation.

YMODEM (this page)

Block-0 metadata, batch, exact size truncation.

Ethernet Gateway

Filename and size arrive first

Identical to XMODEM-1K from here

EOT and the closing block 0

Truncate, then stamp

Announce the file

1K blocks, one ACK each

Close the file, then the batch

XMODEM

YMODEM (this page)

ZMODEM

Kermit

Punter

AT Commands

Telnet

SSH

Character Code Tables

ANSI Escape Sequences