Device::SerialPort - Linux/POSIX emulation of Win32::SerialPort functions.
use Device::SerialPort;
$PortObj = new Device::SerialPort ($PortName)
|| die "Can't open $PortName: $!\n";
# not implemented yet
$PortObj = start Device::SerialPort ($Configuration_File_Name)
|| die "Can't start $Configuration_File_Name: $!\n";
# $Configuration_File_Name not implemented yet
# if you use this, expect future changes
$PortObj = tie (*FH, 'Device::SerialPort', $PortName)
|| die "Can't tie using $PortName: $!\n";
$PortObj->alias("MODEM1");
# before using start, restart, or tie
# not implemented yet
$PortObj->save($Configuration_File_Name)
|| warn "Can't save $Configuration_File_Name: $!\n";
# currently optional after new, POSIX version expected to succeed $PortObj->write_settings;
# rereads file to either return open port to a known state
# or switch to a different configuration on the same port
# not implemented yet
$PortObj->restart($Configuration_File_Name)
|| warn "Can't reread $Configuration_File_Name: $^E\n";
Device::SerialPort->set_test_mode_active(1); # test suite use only
# exported by :PARAM
nocarp || carp "Something fishy";
$a = SHORTsize; # 0xffff
$a = LONGsize; # 0xffffffff
$answer = yes_true("choice"); # 1 or 0
OS_Error unless ($API_Call_OK); # prints error
# most methods can be called two ways:
$PortObj->handshake("xoff"); # set parameter
$flowcontrol = $PortObj->handshake; # current value (scalar)
# The only "list context" method calls from Win32::SerialPort
# currently supported are those for baudrate, parity, databits,
# stopbits, and handshake (which only accept specific input values).
@handshake_opts = $PortObj->handshake; # permitted choices (list)
# similar
$PortObj->baudrate(9600);
$PortObj->parity("odd");
$PortObj->databits(8);
$PortObj->stopbits(1); # POSIX does not support 1.5 stopbits
# these are essentially dummies in POSIX implementation
# the calls exist to support compatibility
$PortObj->buffers(4096, 4096); # returns (4096, 4096)
@max_values = $PortObj->buffer_max; # returns (4096, 4096)
$PortObj->reset_error; # returns 0
# true/false parameters (return scalar context only)
# parameters exist, but message processing not yet fully implemented
$PortObj->user_msg(ON); # built-in instead of warn/die above
$PortObj->error_msg(ON); # translate error bitmasks and carp
$PortObj->parity_enable(F); # faults during input $PortObj->debug(0);
# true/false capabilities (read only)
# most are just constants in the POSIX case
$PortObj->can_baud; # 1
$PortObj->can_databits; # 1
$PortObj->can_stopbits; # 1
$PortObj->can_dtrdsr; # 0 currently
$PortObj->can_handshake; # 1
$PortObj->can_parity_check; # 1
$PortObj->can_parity_config; # 1
$PortObj->can_parity_enable; # 1
$PortObj->can_rlsd; # 0 currently
$PortObj->can_16bitmode; # 0 Win32-specific
$PortObj->is_rs232; # 1
$PortObj->is_modem; # 0 Win32-specific
$PortObj->can_rtscts; # 1
$PortObj->can_xonxoff; # 1
$PortObj->can_xon_char; # 0 use stty
$PortObj->can_spec_char; # 0 use stty
$PortObj->can_interval_timeout; # 1 currently
$PortObj->can_total_timeout; # 0 currently
=head2 Operating Methods
($count_in, $string_in) = $PortObj->read($InBytes); warn "read unsuccessful\n" unless ($count_in == $InBytes);
$count_out = $PortObj->write($output_string); warn "write failed\n" unless ($count_out); warn "write incomplete\n" if ( $count_out != length($output_string) );
if ($string_in = $PortObj->input) { PortObj->write($string_in); }
# simple echo with no control character processing
$PortObj->write_drain; # POSIX replacement for Win32 write_done(1) $PortObj->purge_all; $PortObj->purge_rx; $PortObj->purge_tx;
# controlling outputs from the port $PortObj->dtr_active(T); # sends outputs direct to hardware $PortObj->rts_active(Yes); # returns status of ioctl call
$PortObj->pulse_break_on($milliseconds); # off version is implausible
$PortObj->pulse_rts_on($milliseconds);
$PortObj->pulse_rts_off($milliseconds);
$PortObj->pulse_dtr_on($milliseconds);
$PortObj->pulse_dtr_off($milliseconds);
# sets_bit, delays, resets_bit, delays
$PortObj->read_const_time(100); # const time for read (milliseconds) $PortObj->read_char_time(5); # avg time between read char
# will eventually tie with $Configuration_File_Name
$PortObj = tie (*FH, 'Device::SerialPort', $Portname)
|| die "Can't tie: $!\n"; ## TIEHANDLE ##
print FH "text"; ## PRINT ## $char = getc FH; ## GETC ## syswrite FH, $out, length($out), 0; ## WRITE ## ## $line = <FH>; ## READLINE ## not yet supported ## @lines = <FH>; ## READLINE ## not yet supported printf FH "received: %s", $line; ## PRINTF ## read (FH, $in, 5, 0) or die "$^E"; ## READ ## sysread (FH, $in, 5, 0) or die "$^E"; ## READ ## close FH || warn "close failed"; ## CLOSE ## undef $PortObj; untie *FH; ## DESTROY ##
## $PortObj->linesize(10); # with READLINE not yet supported
## $PortObj->lastline("_GOT_ME_"); # with READLINE, list only
$PortObj->close || warn "close failed";
# release port to OS - needed to reopen
# close will not usually DESTROY the object
# also called as: close FH || warn "close failed";
undef $PortObj;
# preferred unless reopen expected since it triggers DESTROY
# calls $PortObj->close but does not confirm success
# MUST precede untie - do all three IN THIS SEQUENCE before re-tie.
untie *FH;
$PortObj->are_match("text", "\n"); # possible end strings
$PortObj->lookclear; # empty buffers
$PortObj->write("Feed Me:"); # initial prompt
$PortObj->is_prompt("More Food:"); # new prompt after "kill" char
my $gotit = "";
until ("" ne $gotit) {
$gotit = $PortObj->lookfor; # poll until data ready
die "Aborted without match\n" unless (defined $gotit);
sleep 1; # polling sample time
}
printf "gotit = %s\n", $gotit; # input BEFORE the match
my ($match, $after, $pattern, $instead) = $PortObj->lastlook;
# input that MATCHED, input AFTER the match, PATTERN that matched
# input received INSTEAD when timeout without match
printf "lastlook-match = %s -after = %s -pattern = %s\n",
$match, $after, $pattern;
$gotit = $PortObj->lookfor($count); # block until $count chars received
$PortObj->are_match("-re", "pattern", "text");
# possible match strings: "pattern" is a regular expression,
# "text" is a literal string
This module provides an object-based user interface essentially identical to the one provided by the Win32::SerialPort module.
The primary constructor is new with a PortName specified. This will open the port and create the object. The port is not
yet ready for read/write access. First, the desired parameter settings must be established. Since these are tuning constants for an underlying
hardware driver in the Operating System, they are all checked for validity
by the methods that set them. The write_settings method updates the port (and will return True under POSIX). Ports are
opened for binary transfers. A separate binmode is not needed.
The second constructor, start is intended to simplify scripts which need a constant setup. It executes
all the steps from new to
write_settings based on a previously saved configuration. This constructor will return undef on a bad configuration file or failure of a validity check. The returned
object is ready for access.
# NOT yet implemented
$PortObj2 = start Win32::SerialPort ($Configuration_File_Name)
|| die;
The third constructor, tie, will combine the start with Perl's support for tied FileHandles (see perltie). Device::SerialPort will implement the complete set of methods:
TIEHANDLE, PRINT, PRINTF, WRITE, READ, GETC, READLINE, CLOSE, and DESTROY.
Tied FileHandle support is new with Version 0.04 and the READ and READLINE
methods are not yet supported. The implementation attempts to mimic
STDIN/STDOUT behaviour as closely as possible. Currently, the port name is
used in place of a $Configuration_File_Name.
$PortObj2 = tie (*FH, 'Device::SerialPort', $PortName)
|| die;
The tied FileHandle methods may be combined with the Device::SerialPort
methods for read, input, and write as well as other methods. The typical restrictions against mixing print with syswrite do not apply. Since both (tied) read and sysread call the same $ob->READ
method, and since a separate $ob->read method has existed for some time in Device::SerialPort, you should always
use sysread with the tied interface (when it is implemented).
Certain parameters SHOULD be set before executing write_settings. Others will attempt to deduce defaults from the hardware or from other parameters. The Required parameters are:
Any legal value.
One of the following: ``none'', ``odd'', ``even''. If you select anything except ``none'', you will need to set parity_enable.
An integer from 5 to 8.
Legal values are 1 and 2.
One of the following: ``none'', ``rts'', ``xoff''.
Some individual parameters (eg. baudrate) can be changed after the initialization is completed. These will be validated and will update the port as required.
$PortObj = new Device::SerialPort ($PortName) || die "Can't open $PortName: $!\n";
$PortObj->user_msg(ON);
$PortObj->databits(8);
$PortObj->baudrate(9600);
$PortObj->parity("none");
$PortObj->stopbits(1);
$PortObj->handshake("rts")
$PortObj->write_settings;
$PortObj->baudrate(300);
$PortObj->close;
undef $PortObj; # closes port AND frees memory in perl
Use alias to convert the name used by ``built-in'' messages.
$PortObj->alias("FIDO");
Version 0.04 adds pulse methods for the RTS, BREAK, and DTR bits. The pulse methods assume the bit is in the opposite state when the method is called. They set the requested state, delay the specified number of milliseconds, set the opposite state, and again delay the specified time. These methods are designed to support devices, such as the X10 ``FireCracker'' control and some modems, which require pulses on these lines to signal specific events or data. Timing for the active part of pulse_break_on is handled by POSIX::tcsendbreak(0), which sends a 250-500 millisecond BREAK pulse.
$PortObj->pulse_break_on($milliseconds); $PortObj->pulse_rts_on($milliseconds); $PortObj->pulse_rts_off($milliseconds); $PortObj->pulse_dtr_on($milliseconds); $PortObj->pulse_dtr_off($milliseconds);
The Win32 Serial Comm API provides extensive information concerning the capabilities and options available for a specific port (and instance). This module will return suitable responses to facilitate porting code from that environment.
Binary selections will accept as true any of the following:
("YES", "Y", "ON", "TRUE", "T", "1", 1) (upper/lower/mixed case) Anything else is false.
There are a large number of possible configuration and option parameters. To facilitate checking option validity in scripts, most configuration methods can be used in two different ways:
The parameter is set to the argument, if valid. An invalid argument returns false (undef) and the parameter is unchanged. The function will also carp if $user_msg is true. The port will be updated immediately if allowed (an automatic write_settings is called).
The current value is returned. If the value is not initialized either directly or by default, return ``undef'' which will parse to false. For binary selections (true/false), return the current value. All current values from ``multivalue'' selections will parse to true.
Methods which only accept a limited number of specific input values return
a list consisting of all acceptable choices. The null list
(undef) will be returned for failed calls in list context (e.g. for an invalid or
unexpected argument). Only the baudrate, parity, databits, stopbits, and
handshake methods currently support this feature.
Nothing is exported by default. The following tags can be used to have large sets of symbols exported:
Utility subroutines and constants for parameter setting and test:
LONGsize SHORTsize nocarp yes_true
OS_Error
All of the above. Except for the test suite, there is not really a good reason to do this.
The object returned by new is NOT a Filehandle. You will be disappointed if you try to use it as one.
e.g. the following is WRONG!!____print $PortObj "some text";
This module uses POSIX termios extensively. Raw API calls are very unforgiving. You will certainly want to start perl with the -w switch. If you can, use strict as well. Try to ferret out all the syntax and usage problems BEFORE issuing the API calls (many of which modify tuning constants in hardware device drivers....not where you want to look for bugs).
With all the options, this module needs a good tutorial. It doesn't have one yet.
The current version of the module has been tested with Perl 5.003 and above. It was initially ported from Win32 and was designed to be used without requiring a compiler or using XS. Since everything is (sometimes convoluted but still pure) Perl, you can fix flaws and change limits if required. But please file a bug report if you do.
The read method, and tied methods which call it, currently can use a fixed timeout which approximates behavior of the Win32::SerialPort read_const_time and read_char_time methods. It is used internally by select. If the timeout is set to zero, the read call will return immediately.
$PortObj->read_const_time(500); # 500 milliseconds = 0.5 seconds $PortObj->read_char_time(5); # avg time between read char
The timing model defines the total time allowed to complete the operation. A fixed overhead time is added to the product of bytes and per_byte_time.
Read_Total = read_const_time + (read_char_time * bytes_to_read)
Write timeouts and read_interval timeouts are not currently supported.
The module does not currently create or check lockfiles.
With all the currently unimplemented features, we don't need any more. But there probably are some.
__Please send comments and bug reports to wcbirthisel@alum.mit.edu.
($BlockingFlags, $InBytes, $OutBytes, $ErrorFlags) = $PortObj->status; $LatchErrorFlags = $PortObj->reset_error;
$PortObj->read_interval(100); # max time between read char $PortObj->write_char_time(5); $PortObj->write_const_time(100);
xon_limit xoff_limit xon_char xoff_char
eof_char event_char error_char stty_intr
stty_quit stty_eof stty_eol stty_erase
stty_kill is_stty_intr is_stty_quit is_stty_eof
is_stty_eol is_stty_erase is_stty_kill stty_clear
is_stty_clear stty_bsdel stty_echo stty_echoe
stty_echok stty_echonl stty_echoke stty_echoctl
stty_istrip stty_icrnl stty_ocrnl stty_igncr
stty_inlcr stty_onlcr stty_isig stty_icanon
modemlines transmit_char
init_done fetch_DCB update_DCB initialize
are_buffers are_baudrate are_handshake are_parity
are_databits are_stopbits is_handshake xmit_imm_char
is_baudrate is_parity is_databits is_write_char_time
debug_comm is_xon_limit is_xoff_limit is_read_const_time
is_xoff_char is_eof_char is_event_char is_read_char_time
is_read_buf is_write_buf is_buffers is_read_interval
is_error_char is_xon_char is_stopbits is_write_const_time
is_binary is_status write_bg is_parity_enable
is_modemlines read_bg read_done write_bg
xoff_active is_read_buf is_write_buf xon_active
write_done suspend_tx resume_tx break_active
A large number of Win32-specific elements have been omitted. Most of these are only available in Win32::SerialPort and Win32API::CommPort as optional Exports. The list includes the following:
The Constants named BM_*, MS_*, CE_*, and ST_*
The API Wrapper Methods and Constants used only to support them including PURGE_*, SET*, CLR*, EV_*, and ERROR_IO*
The Constants used for Feature and Properties Detection including BAUD_*, PST_*, PCF_*, SP_*, DATABITS_*, STOPBITS_*, PARITY_*, and COMMPROP_INITIALIZED
The constants for the Win32 Device Control Block including CBR_*, DTR_*, RTS_*, *PARITY, *STOPBIT*, and FM_*
This code implements the functions required to support the MisterHouse Home Automation software by Bruce Winter. It does not attempt to support functions from Win32::SerialPort such as stty_emulation that already have POSIX implementations or to replicate Win32 idosyncracies. However, the supported functions are intended to clone the equivalent functions in Win32::SerialPort and Win32API::CommPort. Any discrepancies or omissions should be considered bugs and reported to the maintainer.
Based on Win32::SerialPort.pm, Version 0.8, by Bill Birthisel
Ported to linux/POSIX by Joe Doss for MisterHouse
Currently maintained by: Bill Birthisel, wcbirthisel@alum.mit.edu, http://members.aol.com/Bbirthisel/
Win32API::CommPort
Win32::SerialPort
Perltoot.xxx - Tom (Christiansen)'s Object-Oriented Tutorial
Copyright (C) 1999, Bill Birthisel. All rights reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 9 Apr 1999.