Crate rmodem

rmodem

XMODEM protocol implementation in pure #[no_std] Rust.

This implementation has the goal of supporting as many variants of the XMODEM protocol still in common usage.

If code size becomes an issue, protocol variants may be disabled using feature-gates.

For example, all implemented variants are available by default.

To disable default features, and enable XMODEM-1K support:

[dependencies.rmodem]
# ...
default_features = false
features = ["1k"]

no-std

This crate is #[no_std] by default, making it usable in environments without the std and alloc libraries.

Exception safety

This crate aims to be free from explicit and implicit panics, favoring fallible functions to bubble-up errors.

Lints and manual code review should help in these efforts.

If you notice code that will panic at runtime, it’s a bug.

Please file an issue or submit code changes :)

Compile-time errors, such as failing assertions in proc-macros, do not count since they are caught during compilation.

Usage

As a library

use rmodem::{Control, Error, Result, Sequence, XmodemData, XmodemPacket};

// This would be a packet of data from a file in practice.
let block = [rmodem::CPMEOF; XmodemData::LEN];
let sequence = Sequence::new();

let packet = XmodemPacket::new()
    .with_sequence(sequence)
    .with_data(XmodemData::from_block(&block))
    .into_bytes();

// retry sending the packet, recommended retries is 16
match retry_packet(packet.as_ref(), 16)? {
    Control::Nak => (), // packet NAKed after retries exhausted
    Control::Ack => (), // packet ACKed, continue sending XMODEM packets
    ctrl => return Err(Error::InvalidControl(ctrl.into())), // bad response
}

For a full example of auto-detection and fall-back, see cli binary module.

As a binary

Compile the project with the cli feature:

cargo build --features cli
# for only the original XMODEM
cargo build --features cli --no-default-features
# for all available options
cargo run --features cli -- --help

Currently, the CLI app supports sending files over a serial device:

cargo run --features cli -- --file <file-path> --device <serial-tty> [--baud <baud-rate>]

WIP

The current plan is to support:

• XMODEM
• XMODEM-1k
• XMODEM-CRC
• WXMODEM
• YMODEM
• ZMODEM

If there are other variants still in common usage, please open an issue or submit code changes :)

LICENSE

This code is licensed under AGPL v3.0 or later.

Structs

Checksum

Represents the CRC checksum over XMODEM packet data.

Crc16

Represents the CRC-16 used in XMODEM-CRC (compatible) protocols.

OneKData

Represents an XMODEM variant packet 1 KiB data block.

Sequence

Represents the sequence (seq) number in the XMODEM protocol.

XmodemCrcPacket

Represents an XMODEM/CRC packet.

XmodemData

Represents an original XMODEM packet data block.

XmodemOneKPacket

Represents an XMODEM-1K (compatible) packet.

XmodemPacket

Represents an XMODEM packet.

Enums

Control

Represents XMODEM control bytes.

Error

Represents error variants for the library.

Protocol

Represents the supported XMODEM protocol variants.

Constants

ACK

Positive Acknowledgement control byte.

CAN

Cancel control byte.

CPMEOF

Control Packet Modem End-of-File (Ctrl-Z) control byte.

DLE

Data Link Escape control byte.

EOT

End of Transmission control byte.

IDLE

Idle receiver (XMODEK-1K, ASCII “C”) control byte.

NAK

Negative Acknowledgement control byte.

ONE_K_DATA_LEN

Represents the byte length of OneKData.

SOH

Start of Header control byte.

STX

Start of Transmission control byte.

SYN

Synchronous Idle control byte.

XMODEM_DATA_LEN

Represents the byte length of XmodemData.

XOF

Transmit Off (DC3) control byte.

XON

Transmit On (DC1) control byte.

Type Aliases

Result

Represents the Result type for the library.