NAME

Hardware::UPS::Perl::Connection::Serial - package of methods dealing with connection to a serial port

SYNOPSIS

use Hardware::UPS::Perl::Connection::Serial;

$port   = '/dev/ttyS0';
$serial = new Hardware::UPS::Perl::Connection::Serial $port;

undef $serial;                        # disconnects

DESCRIPTION

Hardware::UPS::Perl::Connection::Serial provides methods dealing with connections to a serial port.

LIST OF METHODS

new

Name:

new - creates a new serial object

Synopsis:

	$serial = Hardware::UPS::Perl::Connection::Serial->new();

	$serial = Hardware::UPS::Perl::Connection::Serial->new($port);

	$serial = Hardware::UPS::Perl::Connection::Serial->new({
	    SerialPort => $port,
	    Logger     => $Logger,
    });

Description:

new initializes a serial object $serial and opens the serial port to connect to, if the port is specified.

new expects either a single argument, the serial port, or an anonymous hash as options consisting of key-value pairs.

Arguments:

$port

optional; serial device; defines a valid serial port.

SerialPort => $port

optional; serial device; defines a valid serial port.

Logger => $logger

optional; a Hardware::UPS::Perl::Logging object; defines a logger; if not specified, a logger sending its output to STDERR is created.

See Also:

"connect", "connected", "disconnect", "getLogger", "getPort", "setLogger", "setPort"

setPort

Name:

setPort - sets the serial device to connect to

Synopsis:

$serial = Hardware::UPS::Perl::Connection::Serial->new();

$serial->setPort($port);

Description:

setPort sets the serial port to connect to and returns the previous port if available, undef otherwise.

Arguments:

$port

serial device; defines a valid serial port.

See Also:

"new", "connect", "connected", "disconnect", "getPort"

getPort

Name:

getPort - gets the serial device being connected to

Synopsis:

$serial = Hardware::UPS::Perl::Connection::Serial->new($port);

$port   = $serial->getPort();

Description:

getPort returns the serial port being connected to.

See Also:

"new", "connect", "connected", "disconnect", "setPort"

setDebugLevel

Name:

setDebugLevel - sets the debug level

Synopsis:

$serial = Hardware::UPS::Perl::Connection::Serial->new();

$serial->setDebugLevel(1);

Description:

setDebugLevel sets the debug level, the higher, the better. It returns the previous one if available, 0 otherwise.

Arguments:

$debugLevel

integer number; defines the debug level.

See Also:

"getDebugLevel"

getDebugLevel

Name:

getDebugLevel - gets the current debug level

Synopsis:

$serial = Hardware::UPS::Perl::Connection::Serial->new();

$debugLevel = $serial->getDebugLevel();

Description:

getDebugLevel returns the current debug level.

See Also:

"setDebugLevel"

setLogger

Name:

setLogger - sets the logger to use

Synopsis:

$serial = Hardware::UPS::Perl::Connection::Serial->new();

$serial->setLogger($logger);

Description:

setLogger sets the logger, a Hardware::UPS::Perl::Logging object, used for logging. setLogger returns the previous logger used.

Arguments:

$logger

required; a Hardware::UPS::Perl:Logging object; defines the logger for logging.

See Also:

"new", "getLogger"

getLogger

Name:

getLogger - gets the current logger for logging

Synopsis:

$serial = Hardware::UPS::Perl::Connection::Serial->new();

$logger = $serial->getLogger();

Description:

getLogger returns the current logger, a Hardware::UPS::Perl::Logging object used for logging, if defined, undef otherwise.

See Also:

"new", "setLogger"

getErrorMessage

Name:

getErrorMessage - gets the internal error message

Synopsis:

$serial = Hardware::UPS::Perl::Connection::Serial->new($port);

unless ($serial->connected()) {
    print STDERR $serial->getErrorMessage($errorMessage), "\n";
    exit 0;
}

Description:

getErrorMessage returns the internal error message, if something went wrong.

connect

Name:

connect - connects to a serial port

Synopsis:

$serial = Hardware::UPS::Perl::Connection::Serial->new();

$serial->connect($port);

Description:

connect connects to a serial port $port using package FileHandle. If there is a connection already and the port has changed, the old connection is dropped, otherwise nothing will be done. If no port is specified, it will be checked whether the port has been previously set by method setPort, and used for the connection, consequently. If no port is available at all. the default port provided by package Hardware::UPS::Perl::Constants will be used, usually being /dev/ttyS0. The serial port will be locked using the Perl builtin function flock, In addition, the serial port settings will be modified to have a Baud rate of 2400, with XON/XOFF flow control enabled and echo off using standard package IO::Stty.

Arguments:

$port

optional; serial device; defines a valid serial port.

See Also:

"new", "connected", "disconnect", "getPort", "setPort"

connected

Name:

connected - tests the connection status

Synopsis:

$serial = Hardware::UPS::Perl::Connection::Serial->new();

$serial->connect($port);
if ($serial->connected()) {
    ...
}

Description:

connected tests the connection status, returning 0, when not connected, and 1 when connected.

See Also:

"new", "connect", "disconnect"

disconnect

Name:

disconnect - disconnects from a serial port

Synopsis:

$serial = Hardware::UPS::Perl::Connection::Serial->new();

$serial->connect($port);
$serial->disconnect();

$serial = Hardware::UPS::Perl::Connection::Serial->new();

$serial->connect($port);
undef $serial;

Description:

disconnect disconnects from a serial port, unlocks it and restores the previous settings of the serial port using package IO::Stty.

Notes:

undef $serial has the same effect as $serial->disconnect().

See Also:

"new", "connect", "connected", "getPort", "setPort"

sendCommand

Name:

sendCommand - sending a command to the serial port

Synopsis:

$serial = Hardware::UPS::Perl::Connection::Serial->new();

$serial->connect($port);
$serial->sendCommand($command, \$response, $responseSize);

Description:

sendCommand sends the command $command appended with the \r to a serial port connected and reads the response from it using the package IO::Select awaiting the size of the response $responseSize.

Arguments:

$command

string; defines a command.

$response

string; the response from the serial port.

$responseSize

integer; the buffer size of the response from the serial port.

See Also:

"new", "connect", "connected", "disconnect"

SEE ALSO

Errno(3pm), Fcntl(3pm), FileHandle(3pm), IO::Select(3pm), Hardware::UPS::Perl::Connection(3pm), Hardware::UPS::Perl::Connection::Net(3pm), Hardware::UPS::Perl::Constants(3pm), Hardware::UPS::Perl::Driver(3pm), Hardware::UPS::Perl::Driver::Megatec(3pm), Hardware::UPS::Perl::General(3pm), Hardware::UPS::Perl::Logging(3pm), Hardware::UPS::Perl::Utils(3pm)

NOTES

Hardware::UPS::Perl::Connection::Serial was inspired by the usv.pl program by Bernd Holzhauer, <www.cc-c.de>. The latest version of this program can be obtained from

http://www.cc-c.de/german/linux/linux_usv.php

Another great resource was the Network UPS Tools site, which can be found at

http://www.networkupstools.org

Hardware::UPS::Perl::Connection::Serial was developed using perl 5.8.8 on a SuSE 10.1 Linux distribution.

BUGS

There are plenty of them for sure. Maybe the embedded pod documentation has to be revised a little bit.

Suggestions to improve Hardware::UPS::Perl::Connection::Serial are welcome, though due to the lack of time it might take a while to incorporate them.

AUTHOR

Copyright (c) 2007 by Christian Reile, <Christian.Reile@t-online.de>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. For further licensing details, please see the file COPYING in the distribution.

cpanm Hardware::UPS::Perl::PID

perl -MCPAN -e shell
install Hardware::UPS::Perl::PID