xmodem

README

XMODEM

A robust XMODEM implementation in Go that supports XMODEM-CRC and XMODEM-1K protocols. This library was created to address limitations in existing Go XMODEM implementations, particularly around XMODEM-CRC support.

Features

• Send and Receive — full bidirectional XMODEM transfers
• Supports XMODEM-128 (checksum), XMODEM-CRC, and XMODEM-1K protocols
• Configurable retries and timeouts
• Automatic protocol detection
• Port interface for testing and non-serial transports
• Simple API for file transfers

Usage

Basic Example

package main

import (
    "bytes"
    "github.com/taigrr/xmodem"
    "github.com/tarm/serial"
)

func main() {
    // Create a new XMODEM instance with a serial port
    x, err := xmodem.New("/dev/ttyUSB0", 115200)
    if err != nil {
        panic(err)
    }

    // Prepare your data
    data := []byte("Hello, XMODEM!")
    buffer := bytes.NewBuffer(data)

    // Send the data
    err = x.Send(*buffer)
    if err != nil {
        panic(err)
    }
}

Receiving a File

package main

import (
    "os"
    "github.com/taigrr/xmodem"
)

func main() {
    x, err := xmodem.New("/dev/ttyUSB0", 115200)
    if err != nil {
        panic(err)
    }

    f, err := os.Create("received.bin")
    if err != nil {
        panic(err)
    }
    defer f.Close()

    // Receive initiates the handshake and writes blocks to the writer
    if err := x.Receive(f); err != nil {
        panic(err)
    }
}

Using the Port Interface (Testing / Non-Serial)

// Any type implementing io.ReadWriter + Flush() works
x := xmodem.NewWithReadWriter(myPort)
x.Mode = xmodem.XMode1K

Protocol Support

• XMODEM-CRC (default) — 128-byte blocks with 16-bit CRC
• XMODEM-1K — 1024-byte blocks with 16-bit CRC
• XMODEM-128 — 128-byte blocks with 8-bit checksum

References

• tarm
• c implementation
• protocol writeup
• nindepedia
• wikipedia
• testing fork

License

Released under the 0BSD license.

Disclaimer

The CRC table implementation in this library is not 0BSD licensed. It is used under fair use for educational and compatibility purposes. Please refer to the original source for licensing details.

Documentation

Overview

Package xmodem implements the XMODEM file transfer protocol with support for XMODEM-128 (checksum), XMODEM-CRC, and XMODEM-1K variants.

Index

• Constants
• Variables
• type Mode
• type Port
• type Xmodem
  • func New(port string, baud int) (*Xmodem, error)
  • func NewWithPort(port *serial.Port) *Xmodem
  • func NewWithReadWriter(port Port) *Xmodem
  • func (x Xmodem) Abort()
  • func (x Xmodem) Receive(w io.Writer) error
  • func (x Xmodem) Send(payload bytes.Buffer) error

Constants

const (
	SOH = 0x01 // Start of Header (128-byte blocks)
	STX = 0x02 // Start of Text (1024-byte blocks)
	EOT = 0x04 // End of Transmission
	ACK = 0x06 // Acknowledge
	DLE = 0x10 // Data Link Escape
	NAK = 0x15 // Negative Acknowledge
	CAN = 0x18 // Cancel
	SUB = 0x1A // Substitute (default padding byte)
	CRC = 'C'  // CRC mode request
)

XMODEM protocol control bytes.

Variables

var (
	// ErrTransferCanceled indicates the transfer was canceled by the remote end
	// or aborted due to too many errors.
	ErrTransferCanceled = errors.New("transfer canceled")

	// ErrSequenceMismatch indicates a received block had an unexpected sequence number.
	ErrSequenceMismatch = errors.New("sequence number mismatch")

	// ErrChecksumMismatch indicates a received block failed checksum or CRC verification.
	ErrChecksumMismatch = errors.New("checksum mismatch")
)

Types

type Mode

type Mode int

Mode represents the XMODEM protocol variant.

const (
	XMode128 Mode = iota // XMODEM-128 with 8-bit checksum
	XModeCRC             // XMODEM-CRC with 16-bit CRC
	XMode1K              // XMODEM-1K with 1024-byte blocks and CRC
)

Mode selects the XMODEM variant for a transfer.

type Port

type Port interface {
	io.ReadWriter
	Flush() error
}

Port abstracts a serial port for reading, writing, and flushing. *serial.Port satisfies this interface. A Read that returns (0, nil) is treated as a timeout/no-progress condition (as tarm/serial does when its ReadTimeout elapses) and counts against the retry budget.

type Xmodem

type Xmodem struct {
	Padding byte
	Mode    Mode

	Timeout time.Duration
	// contains filtered or unexported fields
}

Xmodem manages an XMODEM file transfer over a Port.

func New

func New(port string, baud int) (*Xmodem, error)

func NewWithPort

func NewWithPort(port *serial.Port) *Xmodem

NewWithPort creates an Xmodem instance from an existing serial port.

func NewWithReadWriter

func NewWithReadWriter(port Port) *Xmodem

NewWithReadWriter creates an Xmodem instance from any Port implementation. This is useful for testing or non-serial transports.

func (Xmodem) Abort

func (x Xmodem) Abort()

func (Xmodem) Receive

func (x Xmodem) Receive(w io.Writer) error

Receive accepts an incoming XMODEM transfer and writes the received data to w. The receiver initiates by sending 'C' (for CRC/1K modes) or NAK (for checksum mode) to the sender. If the sender does not respond to 'C' after crcHandshakeAttempts, the receiver falls back to checksum mode (except for XMODEM-1K, which is CRC-only). Blocks are verified and acknowledged until the sender signals end of transmission. Per the XMODEM standard the first EOT is answered with NAK to guard against a noise-induced EOT; the transfer then completes on a confirming EOT (or if the sender, being lenient, does not resend EOT), and resumes if real data arrives instead.

Note: the received data may include trailing padding bytes (default SUB/0x1A) that the sender used to fill the last block. The caller is responsible for stripping padding if the original file size is known.

func (Xmodem) Send

func (x Xmodem) Send(payload bytes.Buffer) error

Send transmits the payload using the XMODEM protocol. The receiver initiates the transfer by sending NAK (checksum mode) or 'C' (CRC mode). Blocks are retransmitted on NAK up to the configured retry limit.