NAME

Device::SerialPort::Xmodem - Xmodem file transfer protocol for Device::SerialPort

SYNOPSIS

  use Device::SerialPort::Xmodem;

DESCRIPTION

This is an Xmodem implementation designed to receive a file using 128 byte blocks. This module is intended to be passed an open and prepared port with active connection.

At this time it can only receive 128 byte blocks, however 1k blocks are in the works. I do plan to write a send functionality soon.

Device::SerialPort::Xmodem::Constants

Synopsis

This is a set of contants that return hex values for the following:

 nul     ^@    0x00    null
 soh     ^A    0x01    start of header 128 byte block
 stx     ^B    0x02    start of header 1k byte block
 eot     ^D    0x04    end of trasmission
 ack     ^E    0x06    acknowlegded
 nak     ^U    0x15    not acknowledged
 can     ^X    0x18    cancel
 C             0x43    C ASCII char
 ctrl_z  ^Z    0x1A    end of file marker

 

Xmodem::Block

Class that represents a single Xmodem data block.

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();
  
  $b->to_string(); # outputs a formated message block

Xmodem::Buffer

Class that implements an Xmodem receive buffer of data blocks. Every block of data is represented by a Device::SerialPort::Xmodem::Block object.

Blocks can be pushed and popped from the buffer. You can retrieve the last block, or the list of blocks from buffer.

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';
  
  print OUTFILE $buf->dump(); # outputs all data of all blocks in order

Device::SerialPort::Xmodem::Send

Control class to initiate and complete a X-modem file transfer in receive mode.

Synopsis

        my $send = Device::SerialPort::Xmodem::Send->new(
                port     => {Device::SerialPort object},
                filename => 'name of file'
        );

        $send->start();

Object methods

new()

Creates a new Device::SerialPort::Xmodem::Send object.

start()

Starts a new transfer until file send is complete. The only parameter accepted is the local filename to be written. This quits if ten timeouts are received per block.

receive_message()

Retreives a message, being an Xmodem command type (such as ack, nak, etc).

handshake()

If a <nak> message is received within 10 seconds returns true.

send_message()

Sends a raw data message. This is typically a message block <soh> created by the block to_string() function.

send_eot()

Sends a <eot> char, this signals to receiver that the file transfer is complete.

abort_transfer()

Sends a cancel <can> char, that signals to receiver that transfer is aborted.

timeouts()

Returns the number of timeouts that have occured, typically this is per message block.

port()

Returns the underlying Device::Serial object.

Device::SerialPort::Xmodem::Receive

Control class to initiate and complete a X-modem file transfer in receive mode.

Synopsis

        my $receive = Device::SerialPort::Xmodem::Receive->new(
                port     => {Device::SerialPort object},
                filename => 'name of file'
        );

        $receive->start();

Object methods

new()

Creates a new Device::SerialPort::Xmodem::Receive object.

start()

Starts a new transfer until file receive is complete. The only parameter accepted is the (optional, default is received.dat) local filename to be written. This quits if ten timeouts are received.

receive_message()

Retreives a message, either being an Xmodem command type (such as ack, nak, etc), or a complete block (soh, blockno, blockno complement, data, checksum).

abort_transfer()

Sends a cancel <can> char, that signals to sender that transfer is aborted.

send_ack()

Sends an acknowledge <ack> char, to signal that we received and stored a correct block. This also resets the count of timeouts.

send_nak()

Sends a <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. Increments count of timeouts.

This also acts as a handshake.

timeouts()

Returns the number of timeouts that have occured, typically this is per message block.

port()

Returns the underlying Device::Serial object.

SEE ALSO

Device::SerialPort

Device::Modem::Protocol::Xmodem

AUTHORS

 Based on Device::Modem::Protocol::Xmodem, version 1.44, by Cosimo Streppone, E<lt>cosimo@cpan.orgE<gt>.
 Ported to Device::SerialPort by Aaron Mitti, E<lt>mitti@cpan.orgE<gt>. 

COPYRIGHT AND LICENCE

 Copyright (C) 2002-2004 Cosimo Streppone, E<lt>cosimo@cpan.orgE<gt>
 Copyright (C) 2005 by Aaron Mitti, E<lt>mitti@cpan.orgE<gt> 

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Device::SerialPort::Xmodem::Constants

perl -MCPAN -e shell
install Device::SerialPort::Xmodem::Constants