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
Portinterface 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)
}
defer x.port.Close()
// 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
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 ¶
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") )
Functions ¶
This section is empty.
Types ¶
type Port ¶
type Port interface {
io.ReadWriter
Flush() error
}
Port abstracts a serial port for reading, writing, and flushing. *serial.Port satisfies this interface.
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 NewWithPort ¶
NewWithPort creates an Xmodem instance from an existing serial port.
func NewWithReadWriter ¶
NewWithReadWriter creates an Xmodem instance from any Port implementation. This is useful for testing or non-serial transports.
func (Xmodem) Receive ¶
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. Blocks are verified and acknowledged until the sender signals end of transmission with EOT.
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.
Source Files
Directories