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