Device...:Xmodem(3pm)

💖 NAME 💖

Device::Modem::Protocol::Xmodem — it's the XModem protocol implementation, bestie! This is a 3pm page, from the User Contributed Perl Documentation collection, and it's basically the whole XModem universe: blocks, buffers, constants, and the receiver that actually does the thing. 🦋

---

🎀 Xmodem::Block 🎀

Okay so this class is the moment — it represents one single Xmodem data block. That's it, that's the whole job. 👑

✨ Synopsis ✨

my $b = Xmodem::Block->new( 1, 'My Data...<until-128-chars>...' );
if( defined $b ) {
    # Ok, block instanced, verify its checksum
    if( $b->verify( 'checksum', <my_chksum> ) ) {
        ...
    } else {
        ...
    }
} else {
    # No block
}

# Calculate checksum, crc16, 32, ...
$crc16 = $b->crc16();
$crc32 = $b->crc32();
$chksm = $b->checksum();

---

🌸 Xmodem::Buffer 🌸

This one is the class that implements an Xmodem receive buffer of data blocks. Every single block of data is represented by an Xmodem::Block object — no exceptions, no shortcuts. 🫶

Blocks can be pushed and popped from the buffer. You can grab the last block, or the whole list of blocks from the buffer. So many options, honestly iconic.

✨ Synopsis ✨

my $buf = Xmodem::Buffer->new();
my $b1  = Xmodem::Block->new(1, 'Data...');

$buf->push($b1);

my $b2  = Xmodem::Block->new(2, 'More data...');
$buf->push($b2);

my $last_block = $buf->last();

print 'now I have ', scalar($buf->blocks()), ' in the buffer';

# TODO document replace() function ???

Not me pointing out the # TODO document replace() function ??? comment — the original literally says that, so it stays. The replace() function is undocumented, and that's canon. 💀

---

🧚 Xmodem::Constants 🧚

A package that contains all the useful Xmodem protocol constants used in handshaking and in the data-block encoding procedures. Your little toolbox of protocol vibes. 🔥

✨ Synopsis ✨

• Xmodem::Constants::soh — 'start of header'
• Xmodem::Constants::eot — 'end of trasmission'
• Xmodem::Constants::ack — 'acknowlegded'
• Xmodem::Constants::nak — 'not acknowledged'
• Xmodem::Constants::can — 'cancel'
• Xmodem::Constants::C — C ASCII char
• Xmodem::Constants::XMODEM — basic xmodem protocol
• Xmodem::Constants::XMODEM_1K — xmodem protocol with 1k blocks
• Xmodem::Constants::XMODEM_CRC — xmodem protocol with CRC checks
• Xmodem::Constants::CHECKSUM — type of block checksum
• Xmodem::Constants::CRC16 — type of block crc16
• Xmodem::Constants::CRC32 — type of block crc32

Bestie, I kept every single spelling exactly as written — trasmission, acknowlegded and all. Not my typos, I promise, that's just how the constants are documented. 🙈

---

👑 Xmodem::Receiver 👑

This is the control class — the main character — that initiates and completes an "X-modem" file transfer in receive mode. 🌈

✨ Synopsis ✨

my $recv = Xmodem::Receiver->new(
    modem    => {Device::Modem object},
    filename => 'name of file',
    XXX protocol => 'xmodem' | 'xmodem-crc', | 'xmodem-1k'
);

$recv->run();

🦋 Object methods 🦋

• abort_transfer() — Sends a cancel char ("can"), which signals to the sender that the transfer is aborted. This gets issued if we receive a bad block number, which usually means we got a bad line. 😭
• modem() — Returns the underlying Device::Modem object. That's the whole method, no cap.
• receive_message() — Retrieves a message from the modem, and if a block is detected it breaks it into the appropriate parts. Slicing and dicing, chef's kiss. 🔪
• run() — Starts a new transfer until the file receive is complete. The only parameter accepted is the (optional) local filename to be written.
• send_ack() — Sends an acknowledge ("ack") char to signal that we received and stored a correct block. Resets the count of timeouts and returns the "Xmodem::Block" object of the data block received. Slay. ✨
• send_timeout() — Sends a timeout ("nak") char to signal that we received a bad block header (either a bad start char or a bad block number), or a bad data checksum. It increments the count of timeouts, and at ten timeouts, it aborts the transfer. Ten strikes and you're out, periodt. 💅

---

🌟 See also 🌟

• Device::Modem

---

And that's the whole page, bestie!! 🎀💜 Written from the Device...:Xmodem(3pm) page — that's the header, folded in right up top like a little bow — and the footer said perl v5.30.3 with a date of 2020-06-20, so shoutout to that version and that day for making this doc exist. Go receive some files. 🦋✨