NAME
VERSION
SYNOPSIS
DESCRIPTION
CONSTRUCTOR
METHODS
NOTE
SEE ALSO
AUTHOR
BUGS
ACKNOWLEDGEMENTS
COPYRIGHT & LICENSE

NAME

Net::Elexol::EtherIO24 - Object interface for manipulating Elexol Ether I/O 24 units with Perl

VERSION

Version 0.18.

Requires Perl 5.8.0.

SYNOPSIS

  use Net::Elexol::EtherIO24;

  Net::Elexol::EtherIO24->debug(1);
  my $eio = Net::Elexol::EtherIO24->new(target_addr=>$addr, threaded=>1);

  for my $line (0..23) {
    print "line $line dir: ".$eio->get_line_dir($line)."  ".
          "line $line val: ".$eio->get_line($line)."\n";
  }

  $eio->close;

DESCRIPTION

The Ether I/O 24 manufactured by Elexol is an inexpensive and simple to use/operate device designed for remote control or remote sensing. It has 24 lines that are each programmable for input or output and a variety of other things.

The control protocol is relatively simplistic and UDP based. This Perl module attempts to abstract this protocol and add other features along the way. In particular, programmers are encouraged to investigate setting direct_writes => 0 and direct_reads => 0 in the constructor for network efficiency (since these are not yet the defaults).

It is thread savvy and will use threads unless told not to. It might perform adequately without threads, but various functionality would be reduced as a result. In particular, the module functions in a nice asynchronous way when it can use threads. Threads support requires Perl 5.8. This module may not function correctly, or even compile, with an older Perl. Your Perl will require Threads to be enabled at compile-time, even if you don't use Threads.

It uses IO::Socket::INET for network I/O and Time::HiRes for timing. It was developed using Perl on a FreeBSD and a Linux system, but has been known to function using Perl with Cygwin or ActivePerl on Windows.

CONSTRUCTOR

new(args, ...): Creates a new Net::Elexol::EtherIO24 object complete with associated socket and any necessary threads (if enabled). Returns undef if this is not possible, whereupon the application can check Net::Elexol::EtherIO24->error() for any relevant error string.; Arguments are given in key => value form from these candidates:

METHODS

close: Closes network resources and waits (briefly) for any running threads to end. Should be called when the host application is ending or when the object is no longer needed.; The object destructor will attempt to call this function when the world ends, but Perl might not be patient enough to wait for threads to end by that time.
debug($level): The higher $level is, the more debugging is output. ``3'' is currently the useful limit, though ``4'' will enable hex-dumps of all data sent and received.; Can be called on the parent to set default debugging level, and on each object to control that objects debug level.
error: Returns a string description of the last error, or 0 if no error recorded.; Note that this value is global - it is shared between all EtherIO24 objects so that you can return an error should new() fail to construct a new object.
dump_packet($packet, $offset, $increment): Returns a string containing a HEX and ASCII dump of the packet in $packet.; This is used in the send/receive routines if a high enough debug level is set and is provided here in case someone else finds it useful.; $offset is optional and specifies the offset in the packet to start at, defaults to 0.; $increment is optional and specifies how many items to display per line, defaults to 16.
clear_cache: Resets the timestamps on all cached data forcing the next read to query the Elexol device.
eeprom_fetch($recv=1, $fetchall=0): Fetch the contents of the eeprom. If recv is 1 then it will wait for the results to arrive, otherwise it returns immediately.; Additionally gets all the reserved and user space words if $fetchall is 1.; Returns 1 on success, 0 on failure.
status_fetch($recv): Query the EtherIO24 for its current status. This will store the current status of all I/O lines and their programmed settings. If you don't intend to reset these settings then this is important in order for the Net::Elexol::EtherIO24 to be able to manipulate I/O lines on a per-bit basis.; If recv is 1 then it will wait for the results to arrive, otherwise it returns immediately.; Returns 1 on success, 0 on failure.
status_send: Send all current status to the EtherIO24.; Returns 1 on success, 0 on failure.
indirect_write_send(): This method performs various background tasks such as sending any updates to the Elexol device that are pending and retrieving status from the device.; It should be called periodically (often) if you aren not using threads; otherwise it is not necessary (but not harmful) to call this.
verify_send_command($cmd): Not normally called directly.; Verify commands to be sent. Returns 1 if the command(s) is(are) valid. Returns 0 if any command is invalud. Will search the entire string given for multiple commands.; Will perform various processing tasks on the command, such as resetting the ``status received'' flags for any status fields referenced by the command.
verify_recv_command($cmd): Not normally called directly.; Verify a command is valid and if so, return how many bytes of it form that valid command or 0 if invalid.; Will perform various tasks on the command, such as updating the stored status of things referenced in the command. When threading, it also sends a signal to indicate that new status has arrived, if relevant.
send_command($cmd): Send a packet to the EtherIO24 unit. Passes it through verify_send_command and then to send_pkt.; Returns 0 on failure, or the result of send_pkt otherwise.
recv_command: Not normally called directly. See recv_result() instead.; Wait for a packet from the EtherIO24 unit. Returns an array of received commands upto any point where an invalid command was found in the input. Is NOT thread-friendly unless used in a particular way!; Received packets are passed through verify_recv_command to parse into commands and perform any automatic processing on them.
recv_result($cmd): Wait for results to arrive. May happen sync or async. Is thread-friendly.; Need to give $cmd for threaded operation so it knows what result in particular to wait for. Returns undef if there was a problem doing this, such as a timeout waiting for the reply.; Replies with the reply command as received, except when it's an eeprom command and threads are being used. In this case the actual command returned is an indeterminate recent eeprom related reply.
send_pkt: Send a packet over the socket. Not normally called directly.
recv_pkt: Wait for a packet to come in. Not normally called directly.
reboot: Restarts the module. Needed to make any eeprom changes take affect.
set_line($line, $val): Sets the line to boolean val and sends to EtherIO module.; Ignored if line is (believed to be) an input.
get_line_live($line): Returns live boolean value of line.
get_line($line): Returns the value of the specified I/O line.; If using direct_reads then this method always queries the device. Otherwise this method uses the cached value, unless expired (See indirect_read_interval constructor parameter) whereupon it will query the device.
set_line_dir($line, $dir): Set line direction. 0 = output, 1 = input.
get_line_dir($line): Returns direction setting for $line. 0 = output, 1 = input.; See get_line for direct_reads and cachine heuristics.
set_line_pullup($line, $pullup): Set input line pullup. 0 = pullup off, 1 = pullup on.
get_line_pullup($line): Returns pullup setting for $line. 0 = pullup off, 1 = pullup on.; See get_line for direct_reads and cachine heuristics.
set_line_thresh($line, $thresh): Set line threshhold. 0 = 2.5v (TTL), 1 = 1.4v (CMOS).
get_line_thresh($line): Returns threshold setting for $line. 0 = 2.5v (TTL), 1 = 1.4v (CMOS).; See get_line for direct_reads and cachine heuristics.
set_line_schmitt($line, $schmitt): Set line Schmitt trigger. 0 = off, 1 = on.
get_line_schmitt($line): Returns schmitt setting for $line. 0 = off, 1 = on.; See get_line for direct_reads and cachine heuristics.
set_autoscan_addr($addr, $port): Programs an IP address to use for autoscan functions.; $addr is an ASCII string representation of an IP address. $port is a numeric UDP port number.; If not specified, it will attempt to determine the current IP address and port of the open UDP socket. This may not always be successful!; If $addr is a numeric 0 then the autoscan function will be disabled on the module.; Changes made by this function require a module restart to take effect.
set_autoscan_line($line, $state): Sets the autoscan state of line $line.; Where $state = 1, the module will send status changes for $line.; Changes made by this function require a module restart to take effect.
set_startup_status($state): If $state is 1, uses the current status to set the startup status. Details such as line direction, trigger levels, etc are programmed into the eeprom. Status from the module is fetched prior to setting the startup status if not pre-fetched at object creation.; Otherwise, disables startup port status setting.; Changes made by this function require a module restart to take effect.

NOTE

The author is not in any way affiliated with Elexol, the manufacturer of the device this Perl module is designed to operate. This module has been developed using only data available in the public domain.

AUTHOR

Chris Luke <chrisy@flirble.org>

BUGS

Please report any bugs or feature requests to bug-net-elexol-etherio24@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

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