NAME

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

VERSION

Version 0.10;

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.

It is thread savvy and will use threads if told to. It should perform adequately without threads, but various functionality is reduced as a result. In particular, the module functions in a nice asynchronous way when it can use threads. Threads supoprt requires Perl 5.8, and this module may not function correctly, or even compile, with an older Perl.

It uses IO::Socket::INET for network I/O. It was developed using Perl on a BSD system, but has been shown to function using Perl with Cygwin and 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:

target_addr

Address or hostname of the device to communicate with. Mandatory.

target_port

UDP port number to communicate on. Defaults to '2424'.

prefetch_status

Indicates that the current status and configuration of ports on the device should be immediately fetched. Defaults to '1', which enables this feature.

presend_status

Indicates that the initial state should be immediately sent to the device. This would set all lines to inputs with no pullups and threshold set to TTL levels. If at some point we add a way to pre-set this status, then this feature might become useful!

threaded

Enables Perl ithreads and creates a thread to listen to replies from the EtherIO24 unit. This currently requires Perl 5.8 to function. For the most part, client applications do not need to be thread aware, but some functionality may change this assumption.

recv_timeout, service_recv_timeout, service_status_fetch

These values control various timers and are unlikely to need any tweaking. However: recv_timeout is the time recv_result will hang around waiting for an answer. service_recv_timeout is the timer used in the packet receiver thread, when threading, to wait for packets before seeing if there's anything else to do. service_status_fetch is how often in that same thread we fire off a call to the status_fetch method, just to keep our status up-to-date, just in case. These timers are all integer seconds.

data

Various state information is contained within a hash. If not given, one is created and used anonymously. However, the application can pass in a reference to a hash here, for whatever reason. Idle curiosity perhaps?

Many of the items in this hash are threads::shared when we are threading.

METHODS

close

Closes network resources and waits (briefly) for any running threads to end. Should be called when the host application is ending.

debug($level)

The higher $level is, the more debugging is output. "3" is currently the useful limit.

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.

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.

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 stored boolean value of line. If it's an input, gets the live value instead.

set_line_dir($line, $dir)

Set line direction. 0 = output, 1 = input.

get_line_dir($line)

Returns (stored) direction setting for $line. 0 = output, 1 = input.

set_line_pullup($line, $pullup)

Set input line pullup. 0 = pullup off, 1 = pullup on.

get_line_pullup($line)

Returns (stored) pullup setting for $line. 0 = pullup off, 1 = pullup on.

set_line_thresh($line, $thresh)

Set line threshhold. 0 = 2.5v (TTL), 1 = 1.4v (CMOS).

get_line_thresh($line)

Returns (stored) threshold setting for $line. 0 = 2.5v (TTL), 1 = 1.4v (CMOS).

set_line_schmitt($line, $schmitt)

Set line Schmitt trigger. 0 = off, 1 = on.

get_line_schmitt($line)

Returns (stored) schmitt setting for $line. 0 = off, 1 = on.

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.

SEE ALSO

http://www.flirble.org/chrisy/elexol/, http://www.elexol.com/, http://www.elexol.com/Downloads/EtherIO24UM11.pdf

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?Queue=Net-Elexol-EtherIO24. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2005 Chris Luke, all rights reserved.

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