Ethernet Gateway

Punter C1 (“New Punter”) is the file-transfer protocol that CCGMS, Novaterm, and StrikeTerm speak natively on Commodore 64/128 BBSes — the one you reach for when the peer is a real C64.

Punter predates and is unrelated to the XMODEM family. Where XMODEM sends a fixed 128-byte block and waits for a single ACK/NAK, Punter C1 is built around a three-token handshake per block (GOO → ACK → S/B → block), two independent per-block checksums, and a two-phase transfer: a short type block that announces the Commodore file type, then the data blocks themselves. Each block also carries the size of the next block, so the receiver always knows exactly how many bytes to read.

The gateway implements single-file C1 in src/punter.rs. It is a clean-room Rust implementation written from Michael Steil's C1 wire description (pagetable.com) and cross-checked against the Novaterm 9.6 / v10 punter.src 6502 source for the corners the prose spec leaves ambiguous — the checksum loop bounds, the handshake direction, and the end-off sequence in particular.

Every Punter C1 block is 7 to 255 bytes: a 7-byte header followed by up to 248 payload bytes.

offset 0   additive checksum   (2 bytes, little-endian)
offset 2   cyclic   checksum   (2 bytes, little-endian)
offset 4   size of NEXT block  (1 byte)
offset 5   block index         (2 bytes, little-endian; high byte 0xFF = final)
offset 7   payload             (0–248 bytes)

Both checksums cover the block from offset 4 to end-of-block — they deliberately skip themselves (the four checksum bytes). Verified against the checksum routine in punter.src: the loop runs from sizepos (offset 4) up to the block's own length.

C1 protects every block with two independent 16-bit checksums computed over the same bytes — a corrupt block almost never satisfies both.

A plain wrapping 16-bit sum of the covered bytes. On the 6502 this is the clc / adc / bcc / inc sequence with carry into the high byte; no carry ever leaves the 16-bit accumulator, so it is exactly a 16-bit add that wraps on overflow.

Per byte: XOR the byte into the low byte of the 16-bit accumulator, then rotate the whole 16-bit accumulator left by one bit, circularly (bit 15 feeds back into bit 0). The rotate happens after the XOR. This is the eor-then-rol/rol pattern in the asm.

The reference implementation, byte for byte:

additive = 0
cyclic   = 0
for b in bytes[4..end]:
    additive = (additive + b) & 0xFFFF        # wrapping add
    cyclic   = cyclic XOR b                     # XOR into low byte
    cyclic   = rotate_left_16(cyclic, 1)        # circular, post-XOR

Both results are written little-endian into the block header (additive at offset 0, cyclic at offset 2). On receive, the gateway recomputes both over the received bytes 4…end and compares; a mismatch on either checksum makes the block bad and triggers a BAD resend request (see Recovery).

Five three-byte ASCII tokens carry all the control signalling. They travel UPPERCASE on the wire.

The asm is authoritative on direction (some prose write-ups get it backwards): the receiver drives with GOO/BAD and S/B; the sender answers ACK and then transmits the block. One data block looks like:

receiver  -> GOO        (or BAD to demand a resend of the same block)
sender    -> ACK
receiver  -> S/B
sender    -> <block bytes>

A C1 transfer runs in two phases: a one-block type phase, then the data phase.

A single 8-byte block whose lone payload byte is the Commodore file type. It tells the receiver what kind of file is coming so the byte stream can be reconstructed faithfully on a CBM filesystem.

Linux has no CBM directory entry to carry this, so the gateway maps it to the filename extension. On send, the outbound type is auto-detected from the extension (.prg / .seq / .usr). On receive, the matching extension is appended when the saved filename lacks one — preserving the round-trip. A type byte outside 0..=3 is treated as Unknown (left without a suffix) rather than silently coerced to SEQ.

The file payload, carried in blocks of up to 248 data bytes each. The first data block is the fixed 7-byte header-only block; every subsequent block's length is announced by the previous block's next-block size field. The final data block is flagged by setting the block index's high byte to 0xFF, after which the two sides run the end-off.

You pull a file from the gateway to your Commodore terminal. The gateway sends; your terminal's receiver drives with GOO / BAD / S/B.

# Phase A — type block
term     <- GOO                          receiver ready
gateway  -> ACK
term     <- S/B
gateway  -> [type block: 1 byte = PRG/SEQ/USR]
# Phase B — data blocks (repeat per block)
term     <- GOO                          (BAD = resend the last block)
gateway  -> ACK
term     <- S/B
gateway  -> [data block, up to 248 bytes] ... until the 0xFF-flagged final block
# End-off
both     <-> SYN handshake
gateway  -> S/B  S/B  S/B                 sender obligation (CCGMS needs all three)

You send a file from your Commodore terminal to the gateway. The gateway receives, so it drives with GOO / BAD / S/B.

# Phase A — type block
gateway  -> GOO                          receiver ready
term     <- ACK
gateway  -> S/B
term     <- [type block: 1 byte = PRG/SEQ/USR]
# Phase B — data blocks (repeat per block)
gateway  -> GOO                          (BAD if the block failed a checksum)
term     <- ACK
gateway  -> S/B
term     <- [data block] ... until the 0xFF-flagged final block
# End-off
both     <-> SYN handshake (tolerant best-effort)

After the final (0xFF-flagged) block, both ends run a closing handshake. Getting it exactly right is what keeps CCGMS from hanging.

The end-off is a SYN exchange followed by the sender transmitting S/B three times. This is a sender obligation: a real CCGMS receiver stalls (the classic “Downloading…” hang) if fewer than three S/B arrive after the final block.

Punter has its own independent settings (separate from the XMODEM and ZMODEM families). Editable from the telnet Configuration → File Transfer menu, the GUI / web File Transfer 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.