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

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

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

    undef $serial;                        # disconnects

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

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"

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"

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"

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"

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"

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"

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"

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.

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"

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"

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"

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"

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)

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.

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.

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.